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

diff --git a/src/cmd/godoc/doc.go b/src/cmd/godoc/doc.go
index 3f0b8e458990b5869e0a00fd91256302690172d5..60c678e130eba142204c8f6c2e3ba4b450bca14e 100644 (file)
--- 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 08dff260d4ef3a76996e16f0e55d60d703649a20..beb38305b06d0d375719a3de132163e39ff5e77e 100644 (file)
--- 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 2e56ec67039913fb7f9bbcc9405b0b3cb057ad11..77f4946da95bd78abed86a5654b755a860ecd416 100644 (file)
--- 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.