Stowage/go
2
0
Fork 0
mirror of https://github.com/golang/go.git synced 2025-12-08 06:10:04 +00:00
Code Issues Projects Releases Packages Wiki Activity

cmd/doc: always print package clause except for commands

Browse source 
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>
This commit is contained in:
Rob Pike 2019-05-17 13:43:51 +10:00
parent 1531192272
commit f736de04aa
1 changed files with 35 additions and 46 deletions
Download patch file Download diff file Expand all files Collapse all files

61
src/cmd/doc/pkg.go
View file

@ -40,9 +40,27 @@ type Package struct {
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
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 @@ func parsePackage(writer io.Writer, pkg *build.Package, userPath string) *Packag
}
}
return &Package{
p := &Package{
writer: writer,
name: pkg.Name,
userPath: userPath,
@ -183,6 +201,8 @@ func parsePackage(writer io.Writer, pkg *build.Package, userPath string) *Packag
build: pkg,
fs: fs,
}
p.buf.pkg = p
return p
}
func (pkg *Package) Printf(format string, args ...interface{}) {
@ -426,9 +446,6 @@ func joinStrings(ss []string) string {
// 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 @@ func (pkg *Package) allDoc() {
// 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 @@ 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
// 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 @@ func (pkg *Package) packageClause(checkUserPath bool) {
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 @@ func (pkg *Package) symbolDoc(symbol string) bool {
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)