From a64b2699c4b9a5bbf73bade7cdc89aca6de57f55 Mon Sep 17 00:00:00 2001 From: Robert Griesemer Date: Thu, 6 Oct 2011 16:06:23 -0700 Subject: [PATCH] godoc: documentation for all (not just exported) declarations Removed the URL form parameter "f=text" in favor of a more flexible mode parameter "m" which now accepts a list of mode flags as documented in doc.go. Fixes #1784. R=rsc CC=golang-dev https://golang.org/cl/5227041 --- src/cmd/godoc/doc.go | 12 +++++++++- src/cmd/godoc/godoc.go | 52 ++++++++++++++++++++++++++++++++---------- src/cmd/godoc/main.go | 7 +++--- 3 files changed, 54 insertions(+), 17 deletions(-) diff --git a/src/cmd/godoc/doc.go b/src/cmd/godoc/doc.go index 3f0b8e45899..60c678e130e 100644 --- a/src/cmd/godoc/doc.go +++ b/src/cmd/godoc/doc.go @@ -124,6 +124,17 @@ via regular expressions). The maximum number of full text search results shown can be set with the -maxresults flag; if set to 0, no full text results are shown, and only an identifier index but no full text search index is created. +The presentation mode of web pages served by godoc can be controlled with the +"m" URL parameter; it accepts a comma-separated list of flag names as value: + + all show documentation for all (not just exported) declarations + src show the original source code rather then the extracted documentation + text present the page in textual (command-line) form rather than HTML + +For instance, http://golang.org/pkg/big/?m=all,text shows the documentation for +all (not just the exported) declarations of package big, in textual form (as +it would appear when using godoc from the command line: "godoc -src big .*"). + By default, godoc serves files from the file system of the underlying OS. Instead, a .zip file may be provided via the -zip flag, which contains the file system to serve. The file paths stored in the .zip file must use @@ -137,7 +148,6 @@ one may run godoc as follows: godoc -http=:6060 -zip=go.zip -goroot=$HOME/go - See "Godoc: documenting Go code" for how to write good comments for godoc: http://blog.golang.org/2011/03/godoc-documenting-go-code.html */ diff --git a/src/cmd/godoc/godoc.go b/src/cmd/godoc/godoc.go index 08dff260d4e..beb38305b06 100644 --- a/src/cmd/godoc/godoc.go +++ b/src/cmd/godoc/godoc.go @@ -816,10 +816,30 @@ const builtinPkgPath = "builtin/" type PageInfoMode uint const ( - exportsOnly PageInfoMode = 1 << iota // only keep exported stuff - genDoc // generate documentation + noFiltering PageInfoMode = 1 << iota // do not filter exports + showSource // show source code, do not extract documentation + noHtml // show result in textual form, do not generate HTML ) +// modeNames defines names for each PageInfoMode flag. +var modeNames = map[string]PageInfoMode{ + "all": noFiltering, + "src": showSource, + "text": noHtml, +} + +// getPageInfoMode computes the PageInfoMode flags by analyzing the request +// URL form value "m". It is value is a comma-separated list of mode names +// as defined by modeNames (e.g.: m=src,text). +func getPageInfoMode(r *http.Request) (mode PageInfoMode) { + for _, k := range strings.Split(r.FormValue("m"), ",") { + if m, found := modeNames[strings.TrimSpace(k)]; found { + mode |= m + } + } + return +} + type PageInfo struct { Dirname string // directory containing the package PList []string // list of package names found @@ -878,6 +898,16 @@ func inList(name string, list []string) bool { return false } +func stripFunctionBodies(pkg *ast.Package) { + for _, f := range pkg.Files { + for _, d := range f.Decls { + if f, ok := d.(*ast.FuncDecl); ok { + f.Body = nil + } + } + } +} + // getPageInfo returns the PageInfo for a package directory abspath. If the // parameter genAST is set, an AST containing only the package exports is // computed (PageInfo.PAst), otherwise package documentation (PageInfo.Doc) @@ -1003,10 +1033,11 @@ func (h *httpHandler) getPageInfo(abspath, relpath, pkgname string, mode PageInf var past *ast.File var pdoc *doc.PackageDoc if pkg != nil { - if mode&exportsOnly != 0 { + if mode&noFiltering == 0 { ast.PackageExports(pkg) } - if mode&genDoc != 0 { + stripFunctionBodies(pkg) + if mode&showSource == 0 { pdoc = doc.NewPackageDoc(pkg, path.Clean(relpath)) // no trailing '/' in importpath } else { past = ast.MergePackageFiles(pkg, ast.FilterUnassociatedComments) @@ -1065,12 +1096,9 @@ func (h *httpHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) { relpath := r.URL.Path[len(h.pattern):] abspath := absolutePath(relpath, h.fsRoot) - var mode PageInfoMode - if relpath != builtinPkgPath { - mode = exportsOnly - } - if r.FormValue("m") != "src" { - mode |= genDoc + mode := getPageInfoMode(r) + if relpath == builtinPkgPath { + mode = noFiltering } info := h.getPageInfo(abspath, relpath, r.FormValue("p"), mode) if info.Err != nil { @@ -1079,7 +1107,7 @@ func (h *httpHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) { return } - if r.FormValue("f") == "text" { + if mode&noHtml != 0 { contents := applyTemplate(packageText, "packageText", info) serveText(w, contents) return @@ -1184,7 +1212,7 @@ func search(w http.ResponseWriter, r *http.Request) { query := strings.TrimSpace(r.FormValue("q")) result := lookup(query) - if r.FormValue("f") == "text" { + if getPageInfoMode(r)&noHtml != 0 { contents := applyTemplate(searchText, "searchText", result) serveText(w, contents) return diff --git a/src/cmd/godoc/main.go b/src/cmd/godoc/main.go index 2e56ec67039..77f4946da95 100644 --- a/src/cmd/godoc/main.go +++ b/src/cmd/godoc/main.go @@ -389,11 +389,10 @@ func main() { var mode PageInfoMode if *srcMode { // only filter exports if we don't have explicit command-line filter arguments - if flag.NArg() == 1 { - mode |= exportsOnly + if flag.NArg() > 1 { + mode |= noFiltering } - } else { - mode = exportsOnly | genDoc + mode |= showSource } // TODO(gri): Provide a mechanism (flag?) to select a package // if there are multiple packages in a directory.