cmd/go,cmd/doc: add "go doc"

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/9227Reviewed-by: Russ Cox <rsc@golang.org>

src/cmd/dist/build.go

@@ -775,17 +775,6 @@ func shouldbuild(file, dir string) bool {
 		return false
 	}
 
-	// cmd/go/doc.go has a giant /* */ comment before
-	// it gets to the important detail that it is not part of
-	// package main.  We don't parse those comments,
-	// so special case that file.
-	if strings.HasSuffix(file, "cmd/go/doc.go") || strings.HasSuffix(file, "cmd\\go\\doc.go") {
-		return false
-	}
-	if strings.HasSuffix(file, "cmd/cgo/doc.go") || strings.HasSuffix(file, "cmd\\cgo\\doc.go") {
-		return false
-	}
-
 	// Check file contents for // +build lines.
 	for _, p := range splitlines(readfile(file)) {
 		p = strings.TrimSpace(p)

src/cmd/doc/main.go

+// Copyright 2015 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// Doc (usually run as go doc) accepts zero or one argument, interpreted as:
+//	go doc
+//	go doc <pkg>
+//	go doc <sym>[.<method>]
+//	go doc [<pkg>].<sym>[.<method>]
+// The first item in this list that succeeds is the one whose documentation
+// is printed. If there is no argument, the package in the current directory
+// is chosen.
+//
+// For complete documentation, run "go help doc".
+package main
+
+import (
+	"flag"
+	"fmt"
+	"go/build"
+	"log"
+	"os"
+	"path"
+	"path/filepath"
+	"strings"
+	"unicode"
+	"unicode/utf8"
+)
+
+var (
+	unexported bool
+)
+
+func init() {
+	flag.BoolVar(&unexported, "unexported", false, "show unexported symbols as well as exported")
+	flag.BoolVar(&unexported, "u", false, "shorthand for -unexported")
+}
+
+// usage is a replacement usage function for the flags package.
+func usage() {
+	fmt.Fprintf(os.Stderr, "Usage of [go] doc:\n")
+	fmt.Fprintf(os.Stderr, "\tgo doc\n")
+	fmt.Fprintf(os.Stderr, "\tgo doc <pkg>\n")
+	fmt.Fprintf(os.Stderr, "\tgo doc <sym>[.<method>]\n")
+	fmt.Fprintf(os.Stderr, "\tgo doc [<pkg>].<sym>[.<method>]\n")
+	fmt.Fprintf(os.Stderr, "For more information run\n")
+	fmt.Fprintf(os.Stderr, "\tgo help doc\n\n")
+	fmt.Fprintf(os.Stderr, "Flags:\n")
+	flag.PrintDefaults()
+	os.Exit(2)
+}
+
+func main() {
+	log.SetFlags(0)
+	log.SetPrefix("doc: ")
+	flag.Usage = usage
+	flag.Parse()
+	buildPackage, symbol := parseArg()
+	symbol, method := parseSymbol(symbol)
+	pkg := parsePackage(buildPackage)
+	switch {
+	case symbol == "":
+		pkg.packageDoc()
+		return
+	case method == "":
+		pkg.symbolDoc(symbol)
+	default:
+		pkg.methodDoc(symbol, method)
+	}
+}
+
+// parseArg analyzes the argument (if any) and returns the package
+// it represents and the symbol (possibly with a .method) within that
+// package. parseSymbol is used to analyze the symbol itself.
+func parseArg() (*build.Package, string) {
+	switch flag.NArg() {
+	default:
+		usage()
+	case 0:
+		// Easy: current directory.
+		return importDir("."), ""
+	case 1:
+		// Done below.
+	}
+	// Usual case: one argument.
+	arg := flag.Arg(0)
+	// If it contains slashes, it begins with a package path.
+	// First, is it a complete package path as it is? If so, we are done.
+	// This avoids confusion over package paths that have other
+	// package paths as their prefix.
+	pkg, err := build.Import(arg, "", build.ImportComment)
+	if err == nil {
+		return pkg, ""
+	}
+	// Another disambiguator: If the symbol starts with an upper
+	// case letter, it can only be a symbol in the current directory.
+	// Kills the problem caused by case-insensitive file systems
+	// matching an upper case name as a package name.
+	if isUpper(arg) {
+		println("HERE", arg)
+		pkg, err := build.ImportDir(".", build.ImportComment)
+		if err == nil {
+			return pkg, arg
+		}
+	}
+	// If it has a slash, it must be a package path but there is a symbol.
+	// It's the last package path we care about.
+	slash := strings.LastIndex(arg, "/")
+	// There may be periods in the package path before or after the slash
+	// and between a symbol and method.
+	// Split the string at various periods to see what we find.
+	// In general there may be ambiguities but this should almost always
+	// work.
+	var period int
+	// slash+1: if there's no slash, the value is -1 and start is 0; otherwise
+	// start is the byte after the slash.
+	for start := slash + 1; start < len(arg); start = period + 1 {
+		period = start + strings.Index(arg[start:], ".")
+		symbol := ""
+		if period < 0 {
+			period = len(arg)
+		} else {
+			symbol = arg[period+1:]
+		}
+		// Have we identified a package already?
+		pkg, err := build.Import(arg[0:period], "", build.ImportComment)
+		if err == nil {
+			return pkg, symbol
+		}
+		// See if we have the basename or tail of a package, as in json for encoding/json
+		// or ivy/value for robpike.io/ivy/value.
+		path := findPackage(arg[0:period])
+		if path != "" {
+			return importDir(path), symbol
+		}
+		if path != "" {
+			return importDir(path), symbol
+		}
+	}
+	// If it has a slash, we've failed.
+	if slash >= 0 {
+		log.Fatalf("no such package %s", arg[0:period])
+	}
+	// Guess it's a symbol in the current directory.
+	return importDir("."), arg
+}
+
+// importDir is just an error-catching wrapper for build.ImportDir.
+func importDir(dir string) *build.Package {
+	pkg, err := build.ImportDir(dir, build.ImportComment)
+	if err != nil {
+		log.Fatal(err)
+	}
+	return pkg
+}
+
+// parseSymbol breaks str apart into a symbol and method.
+// Both may be missing or the method may be missing.
+// If present, each must be a valid Go identifier.
+func parseSymbol(str string) (symbol, method string) {
+	if str == "" {
+		return
+	}
+	elem := strings.Split(str, ".")
+	switch len(elem) {
+	case 1:
+	case 2:
+		method = elem[1]
+		isIdentifier(method)
+	default:
+		log.Printf("too many periods in symbol specification")
+		usage()
+	}
+	symbol = elem[0]
+	isIdentifier(symbol)
+	return
+}
+
+// isIdentifier checks that the name is valid Go identifier, and
+// logs and exits if it is not.
+func isIdentifier(name string) {
+	if len(name) == 0 {
+		log.Fatal("empty symbol")
+	}
+	for i, ch := range name {
+		if unicode.IsLetter(ch) || ch == '_' || i > 0 && unicode.IsDigit(ch) {
+			continue
+		}
+		log.Fatalf("invalid identifier %q", name)
+	}
+}
+
+// isExported reports whether the name is an exported identifier.
+// If the unexported flag (-u) is true, isExported returns true because
+// it means that we treat the name as if it is exported.
+func isExported(name string) bool {
+	return unexported || isUpper(name)
+}
+
+// isUpper reports whether the name starts with an upper case letter.
+func isUpper(name string) bool {
+	ch, _ := utf8.DecodeRuneInString(name)
+	return unicode.IsUpper(ch)
+}
+
+// findPackage returns the full file name path specified by the
+// (perhaps partial) package path pkg.
+func findPackage(pkg string) string {
+	if pkg == "" {
+		return ""
+	}
+	if isUpper(pkg) {
+		return "" // Upper case symbol cannot be a package name.
+	}
+	path := pathFor(build.Default.GOROOT, pkg)
+	if path != "" {
+		return path
+	}
+	for _, root := range splitGopath() {
+		path = pathFor(root, pkg)
+		if path != "" {
+			return path
+		}
+	}
+	return ""
+}
+
+// splitGopath splits $GOPATH into a list of roots.
+func splitGopath() []string {
+	return filepath.SplitList(build.Default.GOPATH)
+}
+
+// pathsFor recursively walks the tree at root looking for possible directories for the package:
+// those whose package path is pkg or which have a proper suffix pkg.
+func pathFor(root, pkg string) (result string) {
+	root = path.Join(root, "src")
+	slashDot := string(filepath.Separator) + "."
+	// We put a slash on the pkg so can use simple string comparison below
+	// yet avoid inadvertent matches, like /foobar matching bar.
+	pkgString := filepath.Clean(string(filepath.Separator) + pkg)
+
+	// We use panic/defer to short-circuit processing at the first match.
+	// A nil panic reports that the path has been found.
+	defer func() {
+		err := recover()
+		if err != nil {
+			panic(err)
+		}
+	}()
+
+	visit := func(pathName string, f os.FileInfo, err error) error {
+		if err != nil {
+			return nil
+		}
+		// One package per directory. Ignore the files themselves.
+		if !f.IsDir() {
+			return nil
+		}
+		// No .git or other dot nonsense please.
+		if strings.Contains(pathName, slashDot) {
+			return filepath.SkipDir
+		}
+		// Is the tail of the path correct?
+		if strings.HasSuffix(pathName, pkgString) {
+			result = pathName
+			panic(nil)
+		}
+		return nil
+	}
+
+	filepath.Walk(root, visit)
+	return "" // Call to panic above sets the real value.
+}

src/cmd/go/alldocs.go

@@ -16,6 +16,7 @@ The commands are:
 
 	build       compile packages and dependencies
 	clean       remove object files
+	doc         show documentation for package or symbol
 	env         print Go environment information
 	fix         run go tool fix on packages
 	fmt         run gofmt on package sources
@@ -183,6 +184,65 @@ For more about build flags, see 'go help build'.
 For more about specifying packages, see 'go help packages'.
 
 
+Show documentation for package or symbol
+
+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 lexically, 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 encoding/json
+		Show documentation for the encoding/json package.
+	go doc json
+		Shorthand for encoding/json.
+	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 json.Number's Int64 method.
+
+Flags:
+	-u
+		Show documentation for unexported as well as exported
+		symbols and methods.
+
+
 Print Go environment information
 
 Usage:

src/cmd/go/doc.go

+// Copyright 2015 The Go Authors.  All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package main
+
+var cmdDoc = &Command{
+	Run:         runDoc,
+	UsageLine:   "doc [-u] [package|[package.]symbol[.method]]",
+	CustomFlags: true,
+	Short:       "show documentation for package or symbol",
+	Long: `
+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 lexically, 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 encoding/json
+		Show documentation for the encoding/json package.
+	go doc json
+		Shorthand for encoding/json.
+	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 json.Number's Int64 method.
+
+Flags:
+	-u
+		Show documentation for unexported as well as exported
+		symbols and methods.
+`,
+}
+
+func runDoc(cmd *Command, args []string) {
+	run(buildToolExec, tool("doc"), args)
+}

src/cmd/go/main.go

@@ -77,6 +77,7 @@ func (c *Command) Runnable() bool {
 var commands = []*Command{
 	cmdBuild,
 	cmdClean,
+	cmdDoc,
 	cmdEnv,
 	cmdFix,
 	cmdFmt,

src/cmd/go/pkg.go

@@ -407,6 +407,7 @@ var goTools = map[string]targetDir{
 	"cmd/asm":                              toTool,
 	"cmd/cgo":                              toTool,
 	"cmd/dist":                             toTool,
+	"cmd/doc":                              toTool,
 	"cmd/fix":                              toTool,
 	"cmd/link":                             toTool,
 	"cmd/nm":                               toTool,