It has two modes.
Without the -http flag, it runs in command-line mode and prints plain text
-documentation to standard output and exits.
+documentation to standard output and exits. If the -src flag is specified,
+godoc prints the exported interface of a package in Go source form, or the
+implementation of a specific exported language entity:
- godoc fmt
- godoc fmt Printf
+ godoc fmt # documentation for package fmt
+ godoc fmt Printf # documentation for fmt.Printf
+ godoc -src fmt # fmt package interface in Go source form
+ godoc -src fmt Printf # implementation of fmt.Printf
In command-line mode, the -q flag enables search queries against a godoc running
as a webserver. If no explicit server address is specified with the -server flag,
single identifier (such as ToLower) or a qualified identifier
(such as math.Sin).
-src
- print exported source in command-line mode
+ print (exported) source in command-line mode
-tabwidth=4
width of tabs in units of spaces
-path=""
const fakePkgFile = "doc.go"
const fakePkgName = "documentation"
+type PageInfoMode uint
+
+const (
+ exportsOnly PageInfoMode = 1 << iota // only keep exported stuff
+ genDoc // generate documentation
+ tryMode // don't log errors
+)
+
type PageInfo struct {
Dirname string // directory containing the package
// directory, PageInfo.PDoc and PageInfo.PExp are nil. If there are no sub-
// directories, PageInfo.Dirs is nil.
//
-func (h *httpHandler) getPageInfo(abspath, relpath, pkgname string, genAST, try bool) PageInfo {
+func (h *httpHandler) getPageInfo(abspath, relpath, pkgname string, mode PageInfoMode) PageInfo {
// filter function to select the desired .go files
filter := func(d *os.Dir) bool {
// If we are looking at cmd documentation, only accept
// get package ASTs
pkgs, err := parser.ParseDir(abspath, filter, parser.ParseComments)
- if err != nil && !try {
+ if err != nil && mode&tryMode != 0 {
// TODO: errors should be shown instead of an empty directory
log.Stderrf("parser.parseDir: %s", err)
}
var past *ast.File
var pdoc *doc.PackageDoc
if pkg != nil {
- ast.PackageExports(pkg)
- if genAST {
- past = ast.MergePackageFiles(pkg, false)
- } else {
+ if mode&exportsOnly != 0 {
+ ast.PackageExports(pkg)
+ }
+ if mode&genDoc != 0 {
pdoc = doc.NewPackageDoc(pkg, pathutil.Clean(relpath)) // no trailing '/' in importpath
+ } else {
+ past = ast.MergePackageFiles(pkg, false)
}
}
relpath := r.URL.Path[len(h.pattern):]
abspath := absolutePath(relpath, h.fsRoot)
- info := h.getPageInfo(abspath, relpath, r.FormValue("p"), r.FormValue("m") == "src", false)
+ mode := exportsOnly
+ if r.FormValue("m") != "src" {
+ mode |= genDoc
+ }
+ info := h.getPageInfo(abspath, relpath, r.FormValue("p"), mode)
if r.FormValue("f") == "text" {
contents := applyTemplate(packageText, "packageText", info)
// http://godoc/ main landing page
// http://godoc/doc/ serve from $GOROOT/doc - spec, mem, tutorial, etc.
// http://godoc/src/ serve files from $GOROOT/src; .go gets pretty-printed
-// http://godoc/cmd/ serve documentation about commands (TODO)
+// http://godoc/cmd/ serve documentation about commands
// http://godoc/pkg/ serve documentation about packages
// (idea is if you say import "compress/zlib", you go to
// http://godoc/pkg/compress/zlib)
import (
"bytes"
+ _ "expvar" // to serve /debug/vars
"flag"
"fmt"
- _ "expvar" // to serve /debug/vars
+ "go/ast"
"http"
_ "http/pprof" // to serve /debug/pprof/*
"io"
"log"
"os"
pathutil "path"
+ "regexp"
"runtime"
+ "strings"
"time"
)
serverAddr = flag.String("server", "", "webserver address for command line searches")
// layout control
- html = flag.Bool("html", false, "print HTML in command-line mode")
- genAST = flag.Bool("src", false, "print exported source in command-line mode")
+ html = flag.Bool("html", false, "print HTML in command-line mode")
+ srcMode = flag.Bool("src", false, "print (exported) source in command-line mode")
// command-line searches
query = flag.Bool("q", false, "arguments are considered search queries")
}
+// Does s look like a regular expression?
+func isRegexp(s string) bool {
+ return strings.IndexAny(s, ".(|)*+?^$[]") >= 0
+}
+
+
+// Make a regular expression of the form
+// names[0]|names[1]|...names[len(names)-1].
+// Returns nil if the regular expression is illegal.
+func makeRx(names []string) (rx *regexp.Regexp) {
+ if len(names) > 0 {
+ s := ""
+ for i, name := range names {
+ if i > 0 {
+ s += "|"
+ }
+ if isRegexp(name) {
+ s += name
+ } else {
+ s += "^" + name + "$" // must match exactly
+ }
+ }
+ rx, _ = regexp.Compile(s) // rx is nil if there's a compilation error
+ }
+ return
+}
+
+
func main() {
flag.Usage = usage
flag.Parse()
// Start indexing goroutine.
go indexer()
- // The server may have been restarted; always wait 1sec to
- // give the forking server a chance to shut down and release
- // the http port.
- // TODO(gri): Do we still need this?
- time.Sleep(1e9)
-
// Start http server.
if err := http.ListenAndServe(*httpAddr, handler); err != nil {
log.Exitf("ListenAndServe %s: %v", *httpAddr, err)
relpath = relativePath(path)
}
+ var mode PageInfoMode
+ if *srcMode {
+ // only filter exports if we don't have explicit command-line filter arguments
+ if flag.NArg() == 1 {
+ mode |= exportsOnly
+ }
+ } else {
+ mode = exportsOnly | genDoc
+ }
// TODO(gri): Provide a mechanism (flag?) to select a package
// if there are multiple packages in a directory.
- info := pkgHandler.getPageInfo(abspath, relpath, "", *genAST, true)
+ info := pkgHandler.getPageInfo(abspath, relpath, "", mode|tryMode)
if info.PAst == nil && info.PDoc == nil && info.Dirs == nil {
// try again, this time assume it's a command
if len(path) > 0 && path[0] != '/' {
abspath = absolutePath(path, cmdHandler.fsRoot)
}
- info = cmdHandler.getPageInfo(abspath, relpath, "", false, false)
+ info = cmdHandler.getPageInfo(abspath, relpath, "", mode)
}
- if info.PDoc != nil && flag.NArg() > 1 {
- args := flag.Args()
- info.PDoc.Filter(args[1:])
+ // If we have more than one argument, use the remaining arguments for filtering
+ if flag.NArg() > 1 {
+ args := flag.Args()[1:]
+ rx := makeRx(args)
+ if rx == nil {
+ log.Exitf("illegal regular expression from %v", args)
+ }
+
+ filter := func(s string) bool { return rx.MatchString(s) }
+ switch {
+ case info.PAst != nil:
+ ast.FilterFile(info.PAst, filter)
+ info.PAst.Doc = nil // don't show package comment in this case
+ case info.PDoc != nil:
+ info.PDoc.Filter(filter)
+ }
}
if err := packageText.Execute(info, os.Stdout); err != nil {
"go/ast"
"go/token"
"regexp"
- "strings"
"sort"
)
// ----------------------------------------------------------------------------
// Filtering by name
-// Does s look like a regular expression?
-func isRegexp(s string) bool {
- return strings.IndexAny(s, ".(|)*+?^$[]") >= 0
-}
-
-
-func match(s string, names []string) bool {
- for _, t := range names {
- if isRegexp(t) {
- if matched, _ := regexp.MatchString(t, s); matched {
- return true
- }
- }
- if s == t {
- return true
- }
- }
- return false
-}
+type Filter func(string) bool
-func matchDecl(d *ast.GenDecl, names []string) bool {
+func matchDecl(d *ast.GenDecl, f Filter) bool {
for _, d := range d.Specs {
switch v := d.(type) {
case *ast.ValueSpec:
for _, name := range v.Names {
- if match(name.Name(), names) {
+ if f(name.Name()) {
return true
}
}
case *ast.TypeSpec:
- if match(v.Name.Name(), names) {
+ if f(v.Name.Name()) {
return true
}
}
}
-func filterValueDocs(a []*ValueDoc, names []string) []*ValueDoc {
+func filterValueDocs(a []*ValueDoc, f Filter) []*ValueDoc {
w := 0
for _, vd := range a {
- if matchDecl(vd.Decl, names) {
+ if matchDecl(vd.Decl, f) {
a[w] = vd
w++
}
}
-func filterFuncDocs(a []*FuncDoc, names []string) []*FuncDoc {
+func filterFuncDocs(a []*FuncDoc, f Filter) []*FuncDoc {
w := 0
for _, fd := range a {
- if match(fd.Name, names) {
+ if f(fd.Name) {
a[w] = fd
w++
}
}
-func filterTypeDocs(a []*TypeDoc, names []string) []*TypeDoc {
+func filterTypeDocs(a []*TypeDoc, f Filter) []*TypeDoc {
w := 0
for _, td := range a {
n := 0 // number of matches
- if matchDecl(td.Decl, names) {
+ if matchDecl(td.Decl, f) {
n = 1
} else {
// type name doesn't match, but we may have matching consts, vars, factories or methods
- td.Consts = filterValueDocs(td.Consts, names)
- td.Vars = filterValueDocs(td.Vars, names)
- td.Factories = filterFuncDocs(td.Factories, names)
- td.Methods = filterFuncDocs(td.Methods, names)
+ td.Consts = filterValueDocs(td.Consts, f)
+ td.Vars = filterValueDocs(td.Vars, f)
+ td.Factories = filterFuncDocs(td.Factories, f)
+ td.Methods = filterFuncDocs(td.Methods, f)
n += len(td.Consts) + len(td.Vars) + len(td.Factories) + len(td.Methods)
}
if n > 0 {
}
-// Filter eliminates information from d that is not
-// about one of the given names.
+// Filter eliminates documentation for names that don't pass through the filter f.
// TODO: Recognize "Type.Method" as a name.
-// TODO(r): maybe precompile the regexps.
//
-func (p *PackageDoc) Filter(names []string) {
- p.Consts = filterValueDocs(p.Consts, names)
- p.Vars = filterValueDocs(p.Vars, names)
- p.Types = filterTypeDocs(p.Types, names)
- p.Funcs = filterFuncDocs(p.Funcs, names)
+func (p *PackageDoc) Filter(f Filter) {
+ p.Consts = filterValueDocs(p.Consts, f)
+ p.Vars = filterValueDocs(p.Vars, f)
+ p.Types = filterTypeDocs(p.Types, f)
+ p.Funcs = filterFuncDocs(p.Funcs, f)
p.Doc = "" // don't show top-level package doc
}