Commit d6a057c9 authored by Cosmos Nicolaou's avatar Cosmos Nicolaou Committed by Robert Griesemer

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
parent 26498684
......@@ -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}}
......
......@@ -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}}{{/*
......
......@@ -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,
......
......@@ -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()
......
......@@ -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.
......
......@@ -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)
}
}
}
......
......@@ -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
......@@ -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
......@@ -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
......@@ -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
......@@ -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
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment