- support to extract one-line package synopsis for package listings

- formatting in dirs.html is crude, needs better html (open to suggestions),
  but shows the synopsis
- many package comments should probably be adjusted such that the first
  sentence is more concise

R=rsc, iant
http://go/go-review/1025014

diff --git a/lib/godoc/dirs.html b/lib/godoc/dirs.html
index 3a0b5b396077e717aa9582c6e1d16492101a09f9..394f2df3c6a50fff9c2ab6270572c63a0dc15224 100644 (file)
--- a/lib/godoc/dirs.html
+++ b/lib/godoc/dirs.html
@@ -1,5 +1,5 @@
 <table class="layout">
-<tr><td colspan="2"><a href="{Path|path}">{Name|html}</a></td></tr>
+<tr><td colspan="2"><a href="{Path|path}">{Name|html}</a></td><td width="10"></td><td>{Text|html}</td></tr>
 {.repeated section Dirs}
        <tr><td width="25"></td><td>{@|dir}</td></tr>
 {.end}

diff --git a/src/cmd/godoc/godoc.go b/src/cmd/godoc/godoc.go
index 9dcdd83c49d4c4cd11044469f6d980a539b0836f..c1dd4ead8e9c01d3536c48f60290c9dc23ef5c8a 100644 (file)
--- a/src/cmd/godoc/godoc.go
+++ b/src/cmd/godoc/godoc.go
@@ -135,12 +135,25 @@ func htmlEscape(s string) string {
 }
 
 
+func firstSentence(s string) string {
+       i := strings.Index(s, ". ");
+       if i < 0 {
+               i = strings.Index(s, ".");
+               if i < 0 {
+                       i = len(s)-1;   // compensate for i+1 below
+               }
+       }
+       return s[0 : i+1];      // include ".", if any
+}
+
+
 // ----------------------------------------------------------------------------
 // Package directories
 
 type Directory struct {
        Path    string; // includes Name
        Name    string;
+       Text    string; // package documentation, if any
        Dirs    []*Directory;
 }
 
@@ -150,7 +163,7 @@ func newDirTree(path, name string, depth int) *Directory {
                // return a dummy directory so that the parent directory
                // doesn't get discarded just because we reached the max
                // directory depth
-               return &Directory{path, name, nil};
+               return &Directory{path, name, "", nil};
        }
 
        list, _ := io.ReadDir(path);    // ignore errors
@@ -158,12 +171,22 @@ func newDirTree(path, name string, depth int) *Directory {
        // determine number of subdirectories and package files
        ndirs := 0;
        nfiles := 0;
+       text := "";
        for _, d := range list {
                switch {
                case isPkgDir(d):
                        ndirs++;
                case isPkgFile(d):
                        nfiles++;
+                       if text == "" {
+                               // no package documentation yet; take the first found
+                               file, err := parser.ParseFile(pathutil.Join(path, d.Name), nil,
+                                       parser.ParseComments | parser.PackageClauseOnly);
+                               if err == nil && file.Name.Value == name && file.Doc != nil {
+                                       // found documentation; extract a synopsys
+                                       text = firstSentence(doc.CommentText(file.Doc));
+                               }
+                       }
                }
        }
 
@@ -190,7 +213,7 @@ func newDirTree(path, name string, depth int) *Directory {
                return nil;
        }
 
-       return &Directory{path, name, dirs};
+       return &Directory{path, name, text, dirs};
 }