cmd/doc: if no top-level symbols match, look for methods

Improving the usability further.

Before:

$ go doc bytes.Read
doc: symbol Read not present in package bytes installed in "bytes"
$

After:
$ go doc bytes.Read
func (b *Buffer) Read(p []byte) (n int, err error)
    Read reads the next len(p) bytes from the buffer or until the buffer is drained.
    The return value n is the number of bytes read. If the buffer has no data to
    return, err is io.EOF (unless len(p) is zero); otherwise it is nil.
func (r *Reader) Read(b []byte) (n int, err error)
$

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

diff --git a/src/cmd/doc/pkg.go b/src/cmd/doc/pkg.go
index 580a91f7e6946101d2ba4eaa1227f09cec1be54c..d52dd978647d71cbd489b16038444ac20d89553e 100644 (file)
--- a/src/cmd/doc/pkg.go
+++ b/src/cmd/doc/pkg.go
@@ -275,9 +275,10 @@ func (pkg *Package) findFuncs(symbol string) (funcs []*doc.Func) {
 }
 
 // findTypes finds the doc.Types that describes the symbol.
+// If symbol is empty, it finds all exported types.
 func (pkg *Package) findTypes(symbol string) (types []*doc.Type) {
        for _, typ := range pkg.doc.Types {
-               if match(symbol, typ.Name) {
+               if symbol == "" && isExported(typ.Name) || match(symbol, typ.Name) {
                        types = append(types, typ)
                }
        }
@@ -298,6 +299,7 @@ func (pkg *Package) findTypeSpec(decl *ast.GenDecl, symbol string) *ast.TypeSpec
 
 // symbolDoc prints the docs for symbol. There may be multiple matches.
 // If symbol matches a type, output includes its methods factories and associated constants.
+// If there is no top-level symbol, symbolDoc looks for methods that match.
 func (pkg *Package) symbolDoc(symbol string) {
        defer pkg.flush()
        found := false
@@ -343,7 +345,10 @@ func (pkg *Package) symbolDoc(symbol string) {
                found = true
        }
        if !found {
-               log.Fatalf("symbol %s not present in package %s installed in %q", symbol, pkg.name, pkg.build.ImportPath)
+               // See if there are methods.
+               if !pkg.printMethodDoc("", symbol) {
+                       log.Printf("symbol %s not present in package %s installed in %q", symbol, pkg.name, pkg.build.ImportPath)
+               }
        }
 }
 
@@ -391,11 +396,16 @@ func trimUnexportedFields(spec *ast.TypeSpec) {
        }
 }
 
-// methodDoc prints the docs for matches of symbol.method.
-func (pkg *Package) methodDoc(symbol, method string) {
+// printMethodDoc prints the docs for matches of symbol.method.
+// If symbol is empty, it prints all methods that match the name.
+// It reports whether it found any methods.
+func (pkg *Package) printMethodDoc(symbol, method string) bool {
        defer pkg.flush()
        types := pkg.findTypes(symbol)
        if types == nil {
+               if symbol == "" {
+                       return false
+               }
                log.Fatalf("symbol %s is not a type in package %s installed in %q", symbol, pkg.name, pkg.build.ImportPath)
        }
        found := false
@@ -409,7 +419,13 @@ func (pkg *Package) methodDoc(symbol, method string) {
                        }
                }
        }
-       if !found {
+       return found
+}
+
+// methodDoc prints the docs for matches of symbol.method.
+func (pkg *Package) methodDoc(symbol, method string) {
+       defer pkg.flush()
+       if !pkg.printMethodDoc(symbol, method) {
                log.Fatalf("no method %s.%s in package %s installed in %q", symbol, method, pkg.name, pkg.build.ImportPath)
        }
 }