- 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

lib/godoc/dirs.html

 <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}

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};
 }