cmd/godoc: add support for display Notes parsed by pkg/go/doc

pkg/go/doc: move BUG notes from Package.Bugs to the general Package.Notes field.
Removing .Bugs would break existing code so it's left in for now.

R=gri, gri, gary.burd, dsymonds, rsc, kevlar
CC=golang-dev
https://golang.org/cl/7341053

diff --git a/lib/godoc/package.html b/lib/godoc/package.html
index 85c737ec3a4cb76e8241c37187acc589f83da7d1..1df1f9151dfd5b25c9b1f09c3201decbf6557cf9 100644 (file)
--- a/lib/godoc/package.html
+++ b/lib/godoc/package.html
@@ -70,12 +70,9 @@
                                        <dd>&nbsp; &nbsp; <a href="#{{$tname_html}}.{{$name_html}}">{{node_html .Decl $.FSet}}</a></dd>
                                {{end}}
                        {{end}}
-                       {{if .Bugs}}
-                               <dd><a href="#pkg-bugs">Bugs</a></dd>
-                       {{end}}
-                       {{if .Notes}}
-                                {{range $marker, $item := .Notes}}
-                               <dd><a href="#pkg-{{$marker}}">{{$marker}}</a></dd>
+                       {{if $.Notes}}
+                                {{range $marker, $item := $.Notes}}
+                               <dd><a href="#pkg-note-{{$marker}}">{{noteTitle $marker | html}}s</a></dd>
                                 {{end}}
                        {{end}}
                        </dl>
@@ -167,15 +164,9 @@
                {{comment_html .Doc}}
        {{end}}
 
-       {{with .Bugs}}
-               <h2 id="pkg-bugs">Bugs</h2>
-               {{range .}}
-               {{comment_html .}}
-               {{end}}
-       {{end}}
-       {{with .Notes}}
+       {{with $.Notes}}
                 {{range $marker, $content := .}}
-                   <h2 id="pkg-{{$marker}}">{{$marker}}</h2>
+                   <h2 id="pkg-note-{{$marker}}">{{noteTitle $marker | html}}s</h2>
                    {{range .}}
                    {{comment_html .}}
                     {{end}}

diff --git a/lib/godoc/package.txt b/lib/godoc/package.txt
index ab9506d65af01a6142938176ad1284d222231e21..94239ca1a5466dab87de34da932e97b99a62c4eb 100644 (file)
--- a/lib/godoc/package.txt
+++ b/lib/godoc/package.txt
@@ -62,13 +62,9 @@ TYPES
 
 ---------------------------------------
 
-*/}}{{with .Bugs}}
-BUGS
-
-{{range .}}{{comment_text . "    " "\t"}}
-{{end}}{{end}}{{with .Notes}}
+*/}}{{with $.Notes}}
 {{range $marker, $content := .}}
-{{$marker}}
+{{noteTitle $marker}}s
 
 {{range $content}}{{comment_text . "    " "\t"}}
 {{end}}{{end}}{{end}}{{end}}{{/*

diff --git a/src/cmd/godoc/godoc.go b/src/cmd/godoc/godoc.go
index 7ca4f83e0a3d537debd6eb7a7cb77731f5eed2a3..74f28835ada8b0c7e2246b4a432d376ddcc6be5c 100644 (file)
--- a/src/cmd/godoc/godoc.go
+++ b/src/cmd/godoc/godoc.go
@@ -446,6 +446,10 @@ func example_suffixFunc(name string) string {
        return suffix
 }
 
+func noteTitle(note string) string {
+       return strings.Title(strings.ToLower(note))
+}
+
 func splitExampleName(s string) (name, suffix string) {
        i := strings.LastIndex(s, "_")
        if 0 <= i && i < len(s)-1 && !startsWithUppercase(s[i+1:]) {
@@ -539,6 +543,9 @@ var fmap = template.FuncMap{
        "example_text":   example_textFunc,
        "example_name":   example_nameFunc,
        "example_suffix": example_suffixFunc,
+
+       // formatting of Notes
+       "noteTitle": noteTitle,
 }
 
 func readTemplate(name string) *template.Template {
@@ -897,11 +904,12 @@ type PageInfo struct {
        Err     error  // error or nil
 
        // package info
-       FSet     *token.FileSet // nil if no package documentation
-       PDoc     *doc.Package   // nil if no package documentation
-       Examples []*doc.Example // nil if no example code
-       PAst     *ast.File      // nil if no AST with package exports
-       IsMain   bool           // true for package main
+       FSet     *token.FileSet      // nil if no package documentation
+       PDoc     *doc.Package        // nil if no package documentation
+       Examples []*doc.Example      // nil if no example code
+       Notes    map[string][]string // nil if no package Notes
+       PAst     *ast.File           // nil if no AST with package exports
+       IsMain   bool                // true for package main
 
        // directory info
        Dirs    *DirList  // nil if no directory information
@@ -1082,6 +1090,17 @@ func (h *docServer) getPageInfo(abspath, relpath string, mode PageInfoMode) (inf
                                log.Println("parsing examples:", err)
                        }
                        info.Examples = collectExamples(pkg, files)
+
+                       // collect any notes that we want to show
+                       if info.PDoc.Notes != nil {
+                               info.Notes = make(map[string][]string)
+                               for _, m := range notesToShow {
+                                       if n := info.PDoc.Notes[m]; n != nil {
+                                               info.Notes[m] = n
+                                       }
+                               }
+                       }
+
                } else {
                        // show source code
                        // TODO(gri) Consider eliminating export filtering in this mode,

diff --git a/src/cmd/godoc/main.go b/src/cmd/godoc/main.go
index 13441009067876e2d733cdc3f190013991be6070..389bb1339df0c62f7bafbbe6752ccb66a779554e 100644 (file)
--- a/src/cmd/godoc/main.go
+++ b/src/cmd/godoc/main.go
@@ -71,6 +71,11 @@ var (
 
        // command-line searches
        query = flag.Bool("q", false, "arguments are considered search queries")
+
+       // which code 'Notes' to show.
+       notes = flag.String("notes", "BUG", "comma separated list of Note markers as per pkg:go/doc")
+       // vector of 'Notes' to show.
+       notesToShow []string
 )
 
 func serveError(w http.ResponseWriter, r *http.Request, relpath string, err error) {
@@ -157,6 +162,8 @@ func main() {
        flag.Usage = usage
        flag.Parse()
 
+       notesToShow = strings.Split(*notes, ",")
+
        // Check usage: either server and no args, command line and args, or index creation mode
        if (*httpAddr != "" || *urlFlag != "") != (flag.NArg() == 0) && !*writeIndex {
                usage()

diff --git a/src/pkg/go/doc/doc.go b/src/pkg/go/doc/doc.go
index 6fc98d49510be5b83994615e912b2611ff684d84..65b1b83eba2fa36df499ecdf293b2fd8a4db8115 100644 (file)
--- a/src/pkg/go/doc/doc.go
+++ b/src/pkg/go/doc/doc.go
@@ -17,7 +17,10 @@ type Package struct {
        ImportPath string
        Imports    []string
        Filenames  []string
-       Bugs       []string
+       // DEPRECATED. For backward compatibility Bugs is still populated,
+       // but all new code should use Notes instead.
+       Bugs []string
+
        // Notes such as TODO(userid): or SECURITY(userid):
        // along the lines of BUG(userid). Any marker with 2 or more upper
        // case [A-Z] letters is recognised.

diff --git a/src/pkg/go/doc/reader.go b/src/pkg/go/doc/reader.go
index 69c11411672774adcb676362ed03554c7131d81a..dd6a57299e62cb073f04f80187b78fb493edd164 100644 (file)
--- a/src/pkg/go/doc/reader.go
+++ b/src/pkg/go/doc/reader.go
@@ -412,7 +412,6 @@ func readNote(c *ast.CommentGroup) (marker, annotation string) {
                        // non-empty MARKER comment; collect comment without the MARKER prefix
                        list := append([]*ast.Comment(nil), c.List...) // make a copy
                        list[0].Text = m[2]
-
                        return m[1], (&ast.CommentGroup{List: list}).Text()
                }
        }
@@ -487,12 +486,9 @@ func (r *reader) readFile(src *ast.File) {
        // collect MARKER(...): annotations
        for _, c := range src.Comments {
                if marker, text := readNote(c); marker != "" {
-                       // Remove r.bugs in a separate CL along with
-                       // any necessary changes to client code.
+                       r.notes[marker] = append(r.notes[marker], text)
                        if marker == "BUG" {
                                r.bugs = append(r.bugs, text)
-                       } else {
-                               r.notes[marker] = append(r.notes[marker], text)
                        }
                }
        }

diff --git a/src/pkg/go/doc/testdata/a.0.golden b/src/pkg/go/doc/testdata/a.0.golden
index 04fe885930980c7068b926c7311d994e80848de2..ae3756c842a47ed0bc689c894789146b5eacd663 100644 (file)
--- a/src/pkg/go/doc/testdata/a.0.golden
+++ b/src/pkg/go/doc/testdata/a.0.golden
@@ -8,13 +8,17 @@ FILENAMES
        testdata/a0.go
        testdata/a1.go
 
+BUGS .Bugs is now deprecated, please use .Notes instead
+       // bug0 
+       // bug1 
+
 BUGS
        // bug0 
        // bug1 
 
-SECBUG
+SECBUGS
        // sec hole 0 need to fix asap 
 
-TODO
+TODOS
        // todo0 
        // todo1 

diff --git a/src/pkg/go/doc/testdata/a.1.golden b/src/pkg/go/doc/testdata/a.1.golden
index 04fe885930980c7068b926c7311d994e80848de2..ae3756c842a47ed0bc689c894789146b5eacd663 100644 (file)
--- a/src/pkg/go/doc/testdata/a.1.golden
+++ b/src/pkg/go/doc/testdata/a.1.golden
@@ -8,13 +8,17 @@ FILENAMES
        testdata/a0.go
        testdata/a1.go
 
+BUGS .Bugs is now deprecated, please use .Notes instead
+       // bug0 
+       // bug1 
+
 BUGS
        // bug0 
        // bug1 
 
-SECBUG
+SECBUGS
        // sec hole 0 need to fix asap 
 
-TODO
+TODOS
        // todo0 
        // todo1 

diff --git a/src/pkg/go/doc/testdata/a.2.golden b/src/pkg/go/doc/testdata/a.2.golden
index 04fe885930980c7068b926c7311d994e80848de2..ae3756c842a47ed0bc689c894789146b5eacd663 100644 (file)
--- a/src/pkg/go/doc/testdata/a.2.golden
+++ b/src/pkg/go/doc/testdata/a.2.golden
@@ -8,13 +8,17 @@ FILENAMES
        testdata/a0.go
        testdata/a1.go
 
+BUGS .Bugs is now deprecated, please use .Notes instead
+       // bug0 
+       // bug1 
+
 BUGS
        // bug0 
        // bug1 
 
-SECBUG
+SECBUGS
        // sec hole 0 need to fix asap 
 
-TODO
+TODOS
        // todo0 
        // todo1 

diff --git a/src/pkg/go/doc/testdata/a0.go b/src/pkg/go/doc/testdata/a0.go
index d2bd146df18d6ef46e4e82a602262fc135ef54d8..71af470eea0a616881a6f900ad6dfde65761f0ca 100644 (file)
--- a/src/pkg/go/doc/testdata/a0.go
+++ b/src/pkg/go/doc/testdata/a0.go
@@ -9,5 +9,9 @@ package a
 
 //TODO(uid): todo0
 
+// A note with some spaces after it, should be ignored (watch out for
+// emacs modes that remove trailing whitespace).
+//NOTE(uid):
+
 // SECBUG(uid): sec hole 0
 // need to fix asap

diff --git a/src/pkg/go/doc/testdata/template.txt b/src/pkg/go/doc/testdata/template.txt
index 489b5d4ea7e0a358b102fa1da6edfc21636a9487..d3882b6b953c7b23f2b71a68570ad34d9f52be4e 100644 (file)
--- a/src/pkg/go/doc/testdata/template.txt
+++ b/src/pkg/go/doc/testdata/template.txt
@@ -60,9 +60,9 @@ TYPES
 {{end}}{{end}}{{end}}{{/*
 
 */}}{{with .Bugs}}
-BUGS
+BUGS .Bugs is now deprecated, please use .Notes instead
 {{range .}}    {{synopsis .}}
 {{end}}{{end}}{{with .Notes}}{{range $marker, $content := .}}
-{{$marker}}
+{{$marker}}S
 {{range $content}}     {{synopsis .}}
 {{end}}{{end}}{{end}}
\ No newline at end of file