cmd/doc: always print package clause except for commands
There was an implicit heuristic before about when to print the
package clause or omit it, but it was undocumented and confusing.
Get rid of it and print it always unless asking for the package
docs for a command, which are more of a usage message than a
programming question. This simplifies the processing.
There are several paths to the output, so to put the fix in one
place we place a wrapper before the output buffer than adds the
clause when Write is first called.
The tests don't verify this behavior, but they didn't before either.
Unsure what the right approach is but this will do for now.
Fixes #31457
Change-Id: Ia6a9e740d556f45265c55f06b5306621c7a40ea9
Reviewed-on: https://go-review.googlesource.com/c/go/+/177797
Reviewed-by: Russ Cox <rsc@golang.org>
diff --git a/src/cmd/doc/pkg.go b/src/cmd/doc/pkg.go
index abc8e0b..2c0c6c1 100644
--- a/src/cmd/doc/pkg.go
+++ b/src/cmd/doc/pkg.go
@@ -31,18 +31,36 @@
)
type Package struct {
- writer io.Writer // Destination for output.
- name string // Package name, json for encoding/json.
- userPath string // String the user used to find this package.
- pkg *ast.Package // Parsed package.
- file *ast.File // Merged from all files in the package
- doc *doc.Package
- build *build.Package
- typedValue map[*doc.Value]bool // Consts and vars related to types.
- constructor map[*doc.Func]bool // Constructors.
- packageClausePrinted bool // Prevent repeated package clauses.
- fs *token.FileSet // Needed for printing.
- buf bytes.Buffer
+ writer io.Writer // Destination for output.
+ name string // Package name, json for encoding/json.
+ userPath string // String the user used to find this package.
+ pkg *ast.Package // Parsed package.
+ file *ast.File // Merged from all files in the package
+ doc *doc.Package
+ build *build.Package
+ typedValue map[*doc.Value]bool // Consts and vars related to types.
+ constructor map[*doc.Func]bool // Constructors.
+ fs *token.FileSet // Needed for printing.
+ buf pkgBuffer
+}
+
+// pkgBuffer is a wrapper for bytes.Buffer that prints a package clause the
+// first time Write is called.
+type pkgBuffer struct {
+ pkg *Package
+ printed bool // Prevent repeated package clauses.
+ bytes.Buffer
+}
+
+func (pb *pkgBuffer) Write(p []byte) (int, error) {
+ if !pb.printed && len(p) > 0 {
+ pb.printed = true
+ // Only show package clause for commands if requested explicitly.
+ if pb.pkg.pkg.Name != "main" || showCmd {
+ pb.pkg.packageClause()
+ }
+ }
+ return pb.Buffer.Write(p)
}
type PackageError string // type returned by pkg.Fatalf.
@@ -171,7 +189,7 @@
}
}
- return &Package{
+ p := &Package{
writer: writer,
name: pkg.Name,
userPath: userPath,
@@ -183,6 +201,8 @@
build: pkg,
fs: fs,
}
+ p.buf.pkg = p
+ return p
}
func (pkg *Package) Printf(format string, args ...interface{}) {
@@ -426,9 +446,6 @@
// allDoc prints all the docs for the package.
func (pkg *Package) allDoc() {
defer pkg.flush()
- if pkg.showInternals() {
- pkg.packageClause(false)
- }
doc.ToText(&pkg.buf, pkg.doc.Doc, "", indent, indentedWidth)
pkg.newlines(1)
@@ -489,14 +506,11 @@
// packageDoc prints the docs for the package (package doc plus one-liners of the rest).
func (pkg *Package) packageDoc() {
defer pkg.flush()
- if pkg.showInternals() {
- pkg.packageClause(false)
- }
doc.ToText(&pkg.buf, pkg.doc.Doc, "", indent, indentedWidth)
pkg.newlines(1)
- if !pkg.showInternals() {
+ if pkg.pkg.Name == "main" && !showCmd {
// Show only package docs for commands.
return
}
@@ -509,29 +523,8 @@
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
-// is empty, meaning it's the current directory.
-func (pkg *Package) packageClause(checkUserPath bool) {
- if pkg.packageClausePrinted {
- return
- }
-
- if checkUserPath {
- if pkg.userPath == "" || pkg.userPath == pkg.build.ImportPath {
- return
- }
- }
-
+func (pkg *Package) packageClause() {
importPath := pkg.build.ImportComment
if importPath == "" {
importPath = pkg.build.ImportPath
@@ -563,7 +556,6 @@
if !usingModules && importPath != pkg.build.ImportPath {
pkg.Printf("WARNING: package source is installed in %q\n", pkg.build.ImportPath)
}
- pkg.packageClausePrinted = true
}
// valueSummary prints a one-line summary for each set of values and constants.
@@ -701,9 +693,6 @@
found := false
// Functions.
for _, fun := range pkg.findFuncs(symbol) {
- if !found {
- pkg.packageClause(true)
- }
// Symbol is a function.
decl := fun.Decl
pkg.emit(fun.Doc, decl)
