go doc vs. godoc
Rob Pike
Now that the type checker and related components are moving into the main repository from x/tools, it's time to consider the correct way to build, install, and deploy vet and godoc, both of which have resided in x/tools since the type checker arrived. (They had to live there rather than in the main repository because the main repository can have no outside dependencies.) Having these tools outside the main repository is annoying and complicates the process of producing binary releases for download.
For Go 1.5, it is clear that vet can move into the main repository. The old location will still exist, for compatibility reasons, until at least the release of 1.6, but it will not be actively maintained. Vet is coming home.
The story with godoc is messier. It has a much larger list of dependencies, many of which will stay in the x/tools repository for the foreseeable future. Thus godoc as it is today must stay where it is. But there is a way to make things better.
Proposal
I propose a way to clean up the release process and improve the situation for all users.
The essence is to resurrect the go tool's doc command (go doc as opposed to godoc) but as an all-new tool that provides command-line level functionality only. This means it need have none of the complex dependencies that burden the full godoc. (It might even be simple enough to be built into the go tool directly rather than as a separate binary, but that is an implementation detail.) The releases would ship with that tool (only), and would therefore be buildable directly from the main repository. People who want to run a local web server or want access to the facilities of the oracle and so on would be required to run go get golang.org/x/tools/cmd/godoc, as they do today when they want to update, but that is a small matter.
There is actually a more interesting reason for a new go doc: it provides the opportunity to design a new, easy to use, more expressive UI for a completely command-line-oriented tool.
The new go doc would be nothing more than a convenient, fast way to see the documentation, as plain text, for a package or one of its components. Several people have already built such tools precisely because of the inconvenient UI of godoc.
Say we wish to check the documentation for net/http's Server.ListenAndServeTLS method to verify the order of its two string arguments. It is not even possible to get it from godoc without getting the rest of the Server type's methods, but even that request has an odd interface:
godoc net/http Server # maybe piped through grep ListenAndServeTLS
(Godoc's syntax is a package path followed by a space and a package-level name). A beginner might expect a more Go-like syntax, and that is in fact what at least one of the new-style command-line-oriented documentation tools does. My own tool godoc.org/robpike.io/cmd/doc has some deep flaws but it does allow the user to ask the specific question more directly and somewhat naturally:
doc http.ListenAndServeTLS
(The syntax here is packagename.exportedname, where exportedname could be an exported method of an exported type.) Actually, it's case insensitive; this works too:
doc http.listenandservetls
and one can even use a regular expression. If we can't remember how to spell it we can ask for all the listen methods (again, with a case-insensitive match):
doc http.listen.*
I am not proposing we adopt the existing doc tool; it has its own idiosyncrasies that should not exist in a generally available and supported program. But as a command-line tool it is nicer to use than godoc for most things already.
I propose we decide to create a new tool to ship with Go 1.5 and spend some time figuring out what its interface should be. The tool itself will be easy to write once the command-line interface is clear.
Here is a proposal for the command-line interface to include with 1.5. It is sure to be refined and extended but I want the starting point to be simple and intuitive. The list may seem long but the examples that follow will show they work well.
Ignore case in symbols: for symbols (not package specifiers) printf matches Printf.
If there are no arguments, show the full documentation for the package in the current directory.
If there is a single argument:
If the argument has no periods after any slash that may be present:
If it has a slash, show the full documentation for the package whose path is exactly the argument (encoding/binary, etc.)
Otherwise it is no slash or period; it is just alphanumeric:
If it matches an exported symbol in the current directory's package, show its documentation.
If it starts with a capital, it must be a symbol in the current directory, but matching is still case-independent (Html will match symbol HTML).
Otherwise if there is a package in $GOPATH with that package name, show its documentation.
Otherwise fail (there is room to do things here; we hold off for now).
Otherwise it has periods. Treat the first period not followed by a slash as the boundary between package and symbol. Use the rules above (package path vs. package name; an empty package specifier refers to the current package) to find the package, then treat the rest of the argument as a symbol, which must be non-empty:
If the symbol has a (second) period, it matches type.method (ignoring whether there is a * in the actual receiver),
Otherwise it matches a package-level symbol
For now, only one argument is accepted. I think doing multiple arguments confuses the matching rules because we would expect consistent heuristics across the arguments. Avoid the issue by allowing only one argument; it's a minor hardship.
Flags:
-list: the argument must specify a package. List its contents in a convenient greppable format.
-pkg: using the rules above, the argument (if any) must match a package; show its package doc comment only.
-std: treat the argument as a package in the standard library to disambiguate arguments that might refer to a local symbol (all packages outside the standard library can be disambiguated using a slash in the package specifier).
Examples:
go doc
Show the current package's documentation.
go doc -list
Show a compact representation of the exported symbols in the current package.
go doc fmt
Show the fmt package's documentation (unless there is a Fmt in the current directory).
go doc -std fmt
Show the fmt package's documentation.
go doc .fmt
Show the documentation for symbol Fmt (etc.) in the current directory.
go doc Fmt
Show the documentation for symbol Fmt in the current directory.
go doc -pkg fmt
Show the package doc comment for package fmt.
go doc -pkg
Show the package doc for the current directory.
go doc encoding/gob
Show the documentation for encoding/gob (and any other package with that package name).
go doc gob
Show the documentation for encoding/gob (only).
go doc gob.Decoder
Show the documentation for encoding/gob's Decoder type.
go doc gob.Decoder.Decode
Show the documentation for encoding/gob's Decoder type's method Decode.
go doc encoding/gob.Decoder.Decode
Equivalent to the previous.
As for what documentation to show, the output will be comparable to the existing godoc rules, for example to show factory-like functions if the symbol is a type.
The program will be installed as go tool doc and will have source in cmd/doc.
-rob
Yongjian Xu
go doc fmt
Show the fmt package's documentation (unless there is a Fmt in the current directory).
go doc -std fmt
Show the fmt package's documentation.
go doc .fmt
Show the documentation for symbol Fmt (etc.) in the current directory.
go doc Fmt
Show the documentation for symbol Fmt in the current directory.
go doc -pkg fmt
Show the package doc comment for package fmt.
go doc -pkg
Show the package doc for the current directory.
go doc encoding/gob
Show the documentation for encoding/gob (and any other package with that package name).
go doc gob
Show the documentation for encoding/gob (only).
go doc gob.Decoder
Show the documentation for encoding/gob's Decoder type.
go doc gob.Decoder.Decode
Show the documentation for encoding/gob's Decoder type's method Decode.
go doc encoding/gob.Decoder.Decode
Equivalent to the previous.
As for what documentation to show, the output will be comparable to the existing godoc rules, for example to show factory-like functions if the symbol is a type.
The program will be installed as go tool doc and will have source in cmd/doc.
-rob
--
You received this message because you are subscribed to the Google Groups "golang-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to golang-dev+...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
Fatih Arslan
output format, like Oracle's `-format` flag. For example oracle has
three output formats: plain, json and xml. The first one is
editor-friendly and it's the one that vim-go uses for displaying the
output in the editor.
For "godoc", currently vim-go shows the whole output and then tries to
simply search for the package identifier (such as Println for the case
fmt.Println). It works but it's not perfect and ther are some work to
improve this situation: https://github.com/fatih/vim-go/issues/361
The current proposal is a welcome one, at least the output can be
modified via the input, such as "go doc gob.Decoder". However it would
be also great if we had the choice of output format too, so we could
plug it into other tools (such as editors).
--
Fatih Arslan
meta keule
...
Matt Sherman
...
Dmitri Shuralyov
...
Steve McCoy
go doc encoding/gob
Show the documentation for encoding/gob (and any other package with that package name).
go doc gob
Show the documentation for encoding/gob (only).
...
Joe Shaw
On Friday, April 17, 2015 at 4:40:49 PM UTC-4, Rob Pike wrote:
...
Russ Cox
Would this proposal allow for the removal of the special cases in which vet and godoc are installed by "go get" into $GOROOT rather than $GOPATH? That would leave only golang.org/x/tools/cmd/cover.
