Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

cmd/go: short commands description in 'go help' too vague for some command #20918

Closed
ensonic opened this issue Jul 6, 2017 · 6 comments
Closed

cmd/go: short commands description in 'go help' too vague for some command #20918

ensonic opened this issue Jul 6, 2017 · 6 comments
Labels
Documentation FrozenDueToAge NeedsDecision Feedback is required from experts, contributors, and/or the community before a change can be made.
Milestone
Go1.10

Comments

@ensonic
Copy link

ensonic commented Jul 6, 2017 •
edited

Please answer these questions before submitting your issue. Thanks!

What version of Go are you using (go version)?

go1.8.1

What operating system and processor architecture are you using (go env)?

GOARCH="amd64"
GOHOSTARCH="amd64"
GOHOSTOS="linux"
GOOS="linux"

What did you do?

$ go help
Go is a tool for managing Go source code.
...
The commands are:

	build       compile packages and dependencies
	clean       remove object files
	doc         show documentation for package or symbol
	env         print Go environment information
	bug         start a bug report
	fix         run go tool fix on packages
	fmt         run gofmt on package sources
	generate    generate Go files by processing source
	get         download and install packages and dependencies
	install     compile and install packages and dependencies
	list        list packages
	run         compile and run Go program
	test        test packages
	tool        run specified go tool
	version     print Go version
	vet         run go tool vet on packages
...

What did you expect to see?

The help output for the fix and vet is not helpful. Is is just ("run go tool %s on packages", toolname). Also the fmt output could be improved.

What did you see instead?

The help-output should say what the command will effectively do (like for vet: check the source code for potential issues).
@ALTree ALTree changed the title bad help output for some tools cmd/go: short description in 'go help' too vague for some tools Jul 6, 2017
@ALTree
Copy link
Member

ALTree commented Jul 6, 2017 •
edited

I guess we could clarify them by adding a very short parenthetical like:

run gofmt (a source code formatter) on package sources

Those strings needs to be really really short, though. I doubt a new description will be approved if it turns out too long.

@ALTree ALTree added the NeedsDecision Feedback is required from experts, contributors, and/or the community before a change can be made. label Jul 6, 2017
@ALTree ALTree changed the title cmd/go: short description in 'go help' too vague for some tools cmd/go: short commands description in 'go help' too vague for some command Jul 6, 2017
@bradfitz bradfitz added this to the Go1.10 milestone Jul 6, 2017
@rsc
Copy link
Contributor

rsc commented Oct 25, 2017

The quoted output is misleading. The full output is:

The commands are:

	build       compile packages and dependencies
	clean       remove object files
	doc         show documentation for package or symbol
	env         print Go environment information
	bug         start a bug report
	fix         run go tool fix on packages
	fmt         run gofmt on package sources
	generate    generate Go files by processing source
	get         download and install packages and dependencies
	install     compile and install packages and dependencies
	list        list packages
	run         compile and run Go program
	test        test packages
	tool        run specified go tool
	version     print Go version
	vet         run go tool vet on packages

Use "go help [command]" for more information about a command.

Note the last line, which is omitted in the bug report. And indeed go help fmt, go help fix, and go help vet do provide more information.

Given this, the current short summaries seem fine.

@rsc rsc closed this as completed Oct 25, 2017
@ensonic
Copy link
Author

ensonic commented Oct 25, 2017

As you wish, but I would expect that the summary would help to tell me what the fmt/fix and vet tools do in general. Like e.g.

-fmt         run gofmt on package sources
+fmt         use gofmt to reformat source files
-fix         run go tool fix on packages
+fix         automatically fix mistakes

@rsc
Copy link
Contributor

rsc commented Oct 25, 2017

I like those specific suggestions. I'll send a CL. Thanks.

@rsc rsc reopened this Oct 25, 2017
@gopherbot
Copy link

Change https://golang.org/cl/73331 mentions this issue: cmd/go: explain fmt, fix, vet a bit more in go help

@ensonic
Copy link
Author

ensonic commented Oct 25, 2017

Thanks!

@ensonic ensonic closed this as completed Oct 25, 2017
gopherbot pushed a commit that referenced this issue Oct 25, 2017
@rsc
cmd/go: explain fmt, fix, vet a bit more in go help
321597b 
Fixes #20918.

Change-Id: I84306242084631bbe7a9adc839f92e72ac1a3e75
Reviewed-on: https://go-review.googlesource.com/73331
Run-TryBot: Russ Cox <rsc@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Ian Lance Taylor <iant@golang.org>
@golang golang locked and limited conversation to collaborators Oct 25, 2018
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
Labels
Documentation FrozenDueToAge NeedsDecision Feedback is required from experts, contributors, and/or the community before a change can be made.
Projects
None yet
Milestone
Go1.10
Development

No branches or pull requests
5 participants
@bradfitz @rsc @ensonic @ALTree @gopherbot