search

golang / gddo

Go Doc Dot Org
https://godoc.org
BSD 3-Clause "New" or "Revised" License
1.1k stars 266 forks source link

Support for showing command-line flags and help for Go CLI tools #574

Open sirnewton01 opened 6 years ago

sirnewton01 commented 6 years ago

I think it would be quite helpful, but perhaps a bit out of scope, for godoc.org to show the help and command-line switches for go packages that represent command-line tools. Imaging that godoc.org could show something that resembles the "--help" for the tool in a code block in the godoc for the package. It should be possible to parse this out from the flag declarations in the code and assemble this help.

sirnewton01 commented 6 years ago

There are a few common flag packages out there. It is unclear whether they could/should be supported. Also, the flag package allows a CLI to do some level of customization of the help that may be difficult to parse out of the source code. Finally, not all flags are declared as vars, which can be a problem.

dominikh commented 6 years ago

This can at best provide an approximation of the actual command line flags, since the creation of flags is dynamic behavior.

I'd argue that it's worse to provide incorrect documentation than no documentation at all.

sirnewton01 commented 6 years ago

It's a fair point. I just thought I'd add this issue as an idea that may or may not work. I can close if it makes no sense to implement.

Since flags are dynamic, perhaps there is some way to run it with "--help" capturing the output instead?

dmitshur commented 6 years ago

It is possible to build commands and run them with -help flag to get the actual help output, but it needs to be done in an environment that supports executing arbitrary code safely. After all, the command can run arbitrary code as part of initializing its flags. godoc.org doesn't have support for that at this time.

I expected us to have an issue open for this already, but I'm not seeing one, so we can use this for tracking the feature request.