Commit 91976aa6 authored by Rob Pike's avatar Rob Pike

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/11953Reviewed-by: default avatarRuss Cox <rsc@golang.org>
parent 1b74c71d
......@@ -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)
......
......@@ -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
......
......@@ -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.
......
......@@ -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.
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment