-
Notifications
You must be signed in to change notification settings - Fork 17.8k
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.
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
all: standardize -help behavior in go project tools #63659
Comments
Unfortunately,
|
Cautious support. I dislike the idea of printing all known documentation every time the command line is incomplete or incorrect. This is a common behavior of a number of tools, although not all. I'm scarred by years of subcommands of various tools printing masses of output when all I need is to be told I typoed a line, or forgot to write "format" instead of "fmt". Programs are too eager to scroll my working text off the screen in the interest of providing full documentation. When mid-flow, too much text can be worse than not enough. If I get the flags wrong, print the flags and nothing else. Otherwise just tell me how to get fuller documentation. Your proposal covers that in a sensible way. So I am supportive, but there is more to lock down, stylewise. For instance, the usage message should not include an essay about all the ways you can use the tool. In fact, by default I think the usage message should always be a single sentence, as in the example above. Your example satisfies this property, but many other commands do not. Answer the question that needs to be answered, and none other, and do it briefly. |
Essentially the opposite of #27580 |
@seankhliao, not quite exactly the opposite, though — arguably much of the verbose |
There should be a proposal to allow |
Traditionally, a problem for Go package documentation was that you would want to put a high level overview into the README for people browsing on GitHub, but that would then need to be duplicated in the Go doc. The pkg site now shows the README, which is good for de-duplication, but maybe go doc could show it too? That plus |
You're right. Here it is: #63696 |
A potential thought experiment could be how to improve This proposal and #27580 complement each other IMO. For example, Ideally, we want |
This proposal has been added to the active column of the proposals project |
Here's a new potential canonical usage message:
|
Sharing some thoughts Russ and I had while developing the example above:
Two helper functions to print each of the last two items, taking the package name (e.g. cmd/gofmt) from runtime/debug.ReadBuildInfo.Path, could potentially be added to the |
Have all remaining concerns about this proposal been addressed? Proposed standard -help format in #63659 (comment). |
Based on the discussion above, this proposal seems like a likely accept. Proposed standard -help format in #63659 (comment). |
No change in consensus, so accepted. 🎉 Proposed standard -help format in #63659 (comment). |
I know this is closed for comments, but I think that setting up an automated check that the manual links aren't broken automatically is prudent if we want the documentation to stay "strong" as domains and webservers move and deteriorate over time. |
Russ and I discussed adding new public functions to the |
UNIX commands vary wildly in the ways in which they provide help messages. Recently in the x/tools repo there has been a trend towards printing the doc.go comment when the -help flag is specified. Following a discussion with @rsc, we propose that all Go-project maintained command-line tools should consider the package doc comment as the primary documentation and print only a brief summary of usage.
Specifically, when a command is invoked with -h, or -help, or with no flags or arguments when this is not a meaningful command, it should print the following items:
go doc package
command for complete documentation.Here's an example of what that would look like for golang.org/x/tools/cmd/callgraph:
Let the bike shedding begin!
The text was updated successfully, but these errors were encountered: