qbit/go
1
0
Fork 0
mirror of https://github.com/golang/go synced 2024-11-20 09:34:52 -07:00
Code Releases Activity

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

Browse Source 
Fixes #953.

R=rsc
CC=golang-dev
https://golang.org/cl/1862046
This commit is contained in:
Robert Griesemer 2010-07-26 15:27:42 -07:00
parent 607eaea456
commit 4188504f38
1 changed files with 34 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

51
src/cmd/godoc/godoc.go
View File

@ -237,27 +237,33 @@ func newDirTree(path, name string, depth, maxDepth int) *Directory {
// determine number of subdirectories and package files // determine number of subdirectories and package files
ndirs := 0 ndirs := 0
nfiles := 0 nfiles := 0
text := "" var synopses [4]string // prioritized package documentation (0 == highest priority)
for _, d := range list { for _, d := range list {
switch { switch {
case isPkgDir(d): case isPkgDir(d):
ndirs++ ndirs++
case isPkgFile(d): case isPkgFile(d):
nfiles++ nfiles++
if text == "" { if synopses[0] == "" {
// no package documentation yet; take the first found // no "optimal" package synopsis yet; continue to collect synopses
file, err := parser.ParseFile(pathutil.Join(path, d.Name), nil, nil, file, err := parser.ParseFile(pathutil.Join(path, d.Name), nil, nil,
parser.ParseComments|parser.PackageClauseOnly) parser.ParseComments|parser.PackageClauseOnly)
if err == nil && if err == nil && file.Doc != nil {
// Also accept fakePkgName, so we get synopses for commmands. // prioritize documentation
// Note: This may lead to incorrect results if there is a i := -1
// (left-over) "documentation" package somewhere in a package switch file.Name.Name() {
// directory of different name, but this is very unlikely and case name:
// against current conventions. i = 0 // normal case: directory name matches package name
(file.Name.Name() == name || file.Name.Name() == fakePkgName) && case fakePkgName:
file.Doc != nil { i = 1 // synopses for commands
// found documentation; extract a synopsys case "main":
text = firstSentence(doc.CommentText(file.Doc)) 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 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 // newDirectory creates a new package directory tree with at most maxDepth
// levels, anchored at root which is relative to goroot. The result tree // levels, anchored at root. The result tree is pruned such that it only
// only contains directories that contain package files or that contain // contains directories that contain package files or that contain
// subdirectories containing package files (transitively). // 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 { func newDirectory(root string, maxDepth int) *Directory {
d, err := os.Lstat(root) d, err := os.Lstat(root)