Add the new go doc command to the go command, installed in
the tool directory.
(Still to do: tests)
Fix cmd/dist to remove old "package documentation" code that was
stopping it from including cmd/go/doc.go in the build.
Implement the doc command. Here is the help info from "go help doc":
===
usage: go doc [-u] [package|[package.]symbol[.method]]
Doc accepts at most one argument, indicating either a package, a symbol within a
package, or a method of a symbol.
go doc
go doc <pkg>
go doc <sym>[.<method>]
go doc [<pkg>].<sym>[.<method>]
Doc interprets the argument to see what it represents, determined by its syntax
and which packages and symbols are present in the source directories of GOROOT and
GOPATH.
The first item in this list that succeeds is the one whose documentation is printed.
For packages, the order of scanning is determined by the file system, however the
GOROOT tree is always scanned before GOPATH.
If there is no package specified or matched, the package in the current directory
is selected, so "go doc" shows the documentation for the current package and
"go doc Foo" shows the documentation for symbol Foo in the current package.
Doc prints the documentation comments associated with the top-level item the
argument identifies (package, type, method) followed by a one-line summary of each
of the first-level items "under" that item (package-level declarations for a
package, methods for a type, etc.)
The package paths must be either a qualified path or a proper suffix of a path
(see examples below). The go tool's usual package mechanism does not apply: package
path elements like . and ... are not implemented by go doc.
When matching symbols, lower-case letters match either case but upper-case letters
match exactly.
Examples:
go doc
Show documentation for current package.
go doc Foo
Show documentation for Foo in the current package.
(Foo starts with a capital letter so it cannot match a package path.)
go doc json
Show documentation for the encoding/json package.
go doc json
Shorthand for encoding/json assuming only one json package
is present in the tree.
go doc json.Number (or go doc json.number)
Show documentation and method summary for json.Number.
go doc json.Number.Int64 (or go doc json.number.int64)
Show documentation for the Int64 method of json.Number.
Flags:
-u
Show documentation for unexported as well as exported
symbols and methods.
===
Still to do:
Tests.
Disambiguation when there is both foo and Foo.
Flag for case-sensitive matching.
Change-Id: I83d409a68688a5445f54297a7e7c745f749b9e66
Reviewed-on: https://go-review.googlesource.com/9227
Reviewed-by: Russ Cox <rsc@golang.org>
