diff options
author | Robert Griesemer <gri@golang.org> | 2010-07-26 15:27:42 -0700 |
---|---|---|
committer | Robert Griesemer <gri@golang.org> | 2010-07-26 15:27:42 -0700 |
commit | 8e0b514a25cd1f09758c951ef3165feccc22e8ee (patch) | |
tree | ba0429726ec97804f57e108c275158204845dee7 | |
parent | 1339cf7a05e6d9418cca7fc6623eac4cf981ae13 (diff) | |
download | go-8e0b514a25cd1f09758c951ef3165feccc22e8ee.tar.gz |
godoc: display synopses for all packages that have some kind of documentation.
Fixes issue 953.
R=rsc
CC=golang-dev
http://codereview.appspot.com/1862046
-rw-r--r-- | src/cmd/godoc/godoc.go | 51 |
1 files changed, 34 insertions, 17 deletions
diff --git a/src/cmd/godoc/godoc.go b/src/cmd/godoc/godoc.go index 61c53e2c3..658749b87 100644 --- 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) |