cmd/doc: suppress symbols for commands when showing package docs

Change the default behavior when showing the package docs
for a command to elide the symbols. This makes

	go doc somecommand

show the top-level package docs only and hide the symbols,
which are probably irrelevant to the user. This has no effect
on explicit requests for internals, such as

	go doc somecommand.sometype

The new -cmd flag restores the old behavior.

Fixes #10733.

Change-Id: I4d363081fe7dabf76ec8e5315770ac3609592f80
Reviewed-on: https://go-review.googlesource.com/11953
Reviewed-by: Russ Cox <rsc@golang.org>

src/cmd/doc/main.go

@@ -23,6 +23,9 @@
 // first argument must be a full package path. This is similar to the
 // command-line usage for the godoc command.
 //
+// For commands, unless the -cmd flag is present "go doc command"
+// shows only the package-level docs for the package.
+//
 // For complete documentation, run "go help doc".
 package main
 
@@ -43,6 +46,7 @@ import (
 var (
 	unexported bool // -u flag
 	matchCase  bool // -c flag
+	showCmd    bool // -cmd flag
 )
 
 // usage is a replacement usage function for the flags package.
@@ -76,6 +80,7 @@ func do(writer io.Writer, flagSet *flag.FlagSet, args []string) (err error) {
 	matchCase = false
 	flagSet.BoolVar(&unexported, "u", false, "show unexported symbols as well as exported")
 	flagSet.BoolVar(&matchCase, "c", false, "symbol matching honors case (paths not affected)")
+	flagSet.BoolVar(&showCmd, "cmd", false, "show symbols with package docs even if package is a command")
 	flagSet.Parse(args)
 	buildPackage, userPath, symbol := parseArgs(flagSet.Args())
 	symbol, method := parseSymbol(symbol)

src/cmd/doc/pkg.go

@@ -200,11 +200,19 @@ func (pkg *Package) oneLineTypeDecl(spec *ast.TypeSpec) {
 // packageDoc prints the docs for the package (package doc plus one-liners of the rest).
 func (pkg *Package) packageDoc() {
 	defer pkg.flush()
-	pkg.packageClause(false)
+	if pkg.showInternals() {
+		pkg.packageClause(false)
+	}
 
 	doc.ToText(&pkg.buf, pkg.doc.Doc, "", "\t", 80)
-	pkg.newlines(2)
+	pkg.newlines(1)
 
+	if !pkg.showInternals() {
+		// Show only package docs for commands.
+		return
+	}
+
+	pkg.newlines(1)
 	pkg.valueSummary(pkg.doc.Consts)
 	pkg.valueSummary(pkg.doc.Vars)
 	pkg.funcSummary(pkg.doc.Funcs)
@@ -212,6 +220,14 @@ func (pkg *Package) packageDoc() {
 	pkg.bugs()
 }
 
+// showInternals reports whether we should show the internals
+// of a package as opposed to just the package docs.
+// Used to decide whether to suppress internals for commands.
+// Called only by Package.packageDoc.
+func (pkg *Package) showInternals() bool {
+	return pkg.pkg.Name != "main" || showCmd
+}
+
 // packageClause prints the package clause.
 // The argument boolean, if true, suppresses the output if the
 // user's argument is identical to the actual package path or

src/cmd/go/alldocs.go

@@ -201,7 +201,9 @@ Given no arguments, that is, when run as
 
 	go doc
 
-it prints the package documentation for the package in the current directory.
+it prints the package documentation for the package in the current directory.  If
+the package is a command (package main), the exported symbols of the package are
+elided from the presentation unless the -cmd flag is provided.
 
 When run with one argument, the argument is treated as a Go-syntax-like representation
 of the item to be documented. What the argument selects depends on what is installed
@@ -249,6 +251,10 @@ Examples:
 		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.
+	go doc cmd/doc
+		Show package docs for the doc command.
+	go doc -cmd cmd/doc
+		Show package docs and exported symbols within the doc command.
 	go doc template.new
 		Show documentation for html/template's New function.
 		(html/template is lexically before text/template)
@@ -260,6 +266,10 @@ Examples:
 Flags:
 	-c
 		Respect case when matching symbols.
+	-cmd
+		Treat a command (package main) like a regular package.
+		Otherwise package main's exported symbols are hidden
+		when showing the package's top-level documentation.
 	-u
 		Show documentation for unexported as well as exported
 		symbols and methods.

src/cmd/go/doc.go

@@ -22,7 +22,9 @@ Given no arguments, that is, when run as
 
 	go doc
 
-it prints the package documentation for the package in the current directory.
+it prints the package documentation for the package in the current directory.  If
+the package is a command (package main), the exported symbols of the package are
+elided from the presentation unless the -cmd flag is provided.
 
 When run with one argument, the argument is treated as a Go-syntax-like representation
 of the item to be documented. What the argument selects depends on what is installed
@@ -70,6 +72,10 @@ Examples:
 		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.
+	go doc cmd/doc
+		Show package docs for the doc command.
+	go doc -cmd cmd/doc
+		Show package docs and exported symbols within the doc command.
 	go doc template.new
 		Show documentation for html/template's New function.
 		(html/template is lexically before text/template)
@@ -81,6 +87,10 @@ Examples:
 Flags:
 	-c
 		Respect case when matching symbols.
+	-cmd
+		Treat a command (package main) like a regular package.
+		Otherwise package main's exported symbols are hidden
+		when showing the package's top-level documentation.
 	-u
 		Show documentation for unexported as well as exported
 		symbols and methods.