godoc: display synopses for all packages that have some kind of documentation.

Fixes #953.

R=rsc
CC=golang-dev
https://golang.org/cl/1862046

diff --git a/src/cmd/godoc/godoc.go b/src/cmd/godoc/godoc.go
index 61c53e2c39bf0e80eeccb245a74311125fc068e5..658749b879fd5d85e8d06bb75973ec89427369e5 100644 (file)
--- a/src/cmd/godoc/godoc.go
+++ b/src/cmd/godoc/godoc.go
@@ -237,27 +237,33 @@ func newDirTree(path, name string, depth, maxDepth int) *Directory {
        // determine number of subdirectories and package files
        ndirs := 0
        nfiles := 0
-       text := ""
+       var synopses [4]string // prioritized package documentation (0 == highest priority)
        for _, d := range list {
                switch {
                case isPkgDir(d):
                        ndirs++
                case isPkgFile(d):
                        nfiles++
-                       if text == "" {
-                               // no package documentation yet; take the first found
+                       if synopses[0] == "" {
+                               // no "optimal" package synopsis yet; continue to collect synopses
                                file, err := parser.ParseFile(pathutil.Join(path, d.Name), nil, nil,
                                        parser.ParseComments|parser.PackageClauseOnly)
-                               if err == nil &&
-                                       // Also accept fakePkgName, so we get synopses for commmands.
-                                       // Note: This may lead to incorrect results if there is a
-                                       // (left-over) "documentation" package somewhere in a package
-                                       // directory of different name, but this is very unlikely and
-                                       // against current conventions.
-                                       (file.Name.Name() == name || file.Name.Name() == fakePkgName) &&
-                                       file.Doc != nil {
-                                       // found documentation; extract a synopsys
-                                       text = firstSentence(doc.CommentText(file.Doc))
+                               if err == nil && file.Doc != nil {
+                                       // prioritize documentation
+                                       i := -1
+                                       switch file.Name.Name() {
+                                       case name:
+                                               i = 0 // normal case: directory name matches package name
+                                       case fakePkgName:
+                                               i = 1 // synopses for commands
+                                       case "main":
+                                               i = 2 // directory contains a main package
+                                       default:
+                                               i = 3 // none of the above
+                                       }
+                                       if 0 <= i && i < len(synopses) && synopses[i] == "" {
+                                               synopses[i] = firstSentence(doc.CommentText(file.Doc))
+                                       }
                                }
                        }
                }
@@ -286,14 +292,25 @@ func newDirTree(path, name string, depth, maxDepth int) *Directory {
                return nil
        }
 
-       return &Directory{depth, path, name, text, dirs}
+       // select the highest-priority synopsis for the directory entry, if any
+       synopsis := ""
+       for _, synopsis = range synopses {
+               if synopsis != "" {
+                       break
+               }
+       }
+
+       return &Directory{depth, path, name, synopsis, dirs}
 }
 
 
 // newDirectory creates a new package directory tree with at most maxDepth
-// levels, anchored at root which is relative to goroot. The result tree
-// only contains directories that contain package files or that contain
-// subdirectories containing package files (transitively).
+// levels, anchored at root. The result tree is pruned such that it only
+// contains directories that contain package files or that contain
+// subdirectories containing package files (transitively). If maxDepth is
+// too shallow, the leaf nodes are assumed to contain package files even if
+// their contents are not known (i.e., in this case the tree may contain
+// directories w/o any package files).
 //
 func newDirectory(root string, maxDepth int) *Directory {
        d, err := os.Lstat(root)