145 lines
5.6 KiB
Go
145 lines
5.6 KiB
Go
// Copyright 2009 The Go Authors. All rights reserved.
|
|
// Use of this source code is governed by a BSD-style
|
|
// license that can be found in the LICENSE file.
|
|
|
|
/*
|
|
|
|
Godoc extracts and generates documentation for Go programs.
|
|
|
|
It has two modes.
|
|
|
|
Without the -http flag, it runs in command-line mode and prints plain text
|
|
documentation to standard output and exits. If both a library package and
|
|
a command with the same name exists, using the prefix cmd/ will force
|
|
documentation on the command rather than the library package. 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 # documentation for package fmt
|
|
godoc fmt Printf # documentation for fmt.Printf
|
|
godoc cmd/go # force documentation for the go command
|
|
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,
|
|
godoc first tries localhost:6060 and then http://golang.org.
|
|
|
|
godoc -q Reader
|
|
godoc -q math.Sin
|
|
godoc -server=:6060 -q sin
|
|
|
|
With the -http flag, it runs as a web server and presents the documentation as a
|
|
web page.
|
|
|
|
godoc -http=:6060
|
|
|
|
Usage:
|
|
godoc [flag] package [name ...]
|
|
|
|
The flags are:
|
|
-v
|
|
verbose mode
|
|
-q
|
|
arguments are considered search queries: a legal query is a
|
|
single identifier (such as ToLower) or a qualified identifier
|
|
(such as math.Sin)
|
|
-src
|
|
print (exported) source in command-line mode
|
|
-tabwidth=4
|
|
width of tabs in units of spaces
|
|
-timestamps=true
|
|
show timestamps with directory listings
|
|
-index
|
|
enable identifier and full text search index
|
|
(no search box is shown if -index is not set)
|
|
-index_files=""
|
|
glob pattern specifying index files; if not empty,
|
|
the index is read from these files in sorted order
|
|
-index_throttle=0.75
|
|
index throttle value; a value of 0 means no time is allocated
|
|
to the indexer (the indexer will never finish), a value of 1.0
|
|
means that index creation is running at full throttle (other
|
|
goroutines may get no time while the index is built)
|
|
-links=true:
|
|
link identifiers to their declarations
|
|
-write_index=false
|
|
write index to a file; the file name must be specified with
|
|
-index_files
|
|
-maxresults=10000
|
|
maximum number of full text search results shown
|
|
(no full text index is built if maxresults <= 0)
|
|
-notes="BUG"
|
|
regular expression matching note markers to show
|
|
(e.g., "BUG|TODO", ".*")
|
|
-html
|
|
print HTML in command-line mode
|
|
-goroot=$GOROOT
|
|
Go root directory
|
|
-http=addr
|
|
HTTP service address (e.g., '127.0.0.1:6060' or just ':6060')
|
|
-server=addr
|
|
webserver address for command line searches
|
|
-analysis=type,pointer
|
|
comma-separated list of analyses to perform
|
|
"type": display identifier resolution, type info, method sets,
|
|
'implements', and static callees
|
|
"pointer" display channel peers, callers and dynamic callees
|
|
(significantly slower)
|
|
See http://golang.org/lib/godoc/analysis/help.html for details.
|
|
-templates=""
|
|
directory containing alternate template files; if set,
|
|
the directory may provide alternative template files
|
|
for the files in $GOROOT/lib/godoc
|
|
-url=path
|
|
print to standard output the data that would be served by
|
|
an HTTP request for path
|
|
-zip=""
|
|
zip file providing the file system to serve; disabled if empty
|
|
|
|
By default, godoc looks at the packages it finds via $GOROOT and $GOPATH (if set).
|
|
This behavior can be altered by providing an alternative $GOROOT with the -goroot
|
|
flag.
|
|
|
|
When godoc runs as a web server and -index is set, a search index is maintained.
|
|
The index is created at startup.
|
|
|
|
The index contains both identifier and full text search information (searchable
|
|
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 declarations, not just the exported ones
|
|
methods show all embedded methods, not just those of unexported anonymous fields
|
|
src show the original source code rather then the extracted documentation
|
|
text present the page in textual (command-line) form rather than HTML
|
|
flat present flat (not indented) directory listings using full paths
|
|
|
|
For instance, http://golang.org/pkg/math/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 math/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
|
|
slash ('/') as path separator; and they must be unrooted. $GOROOT (or -goroot)
|
|
must be set to the .zip file directory path containing the Go root directory.
|
|
For instance, for a .zip file created by the command:
|
|
|
|
zip go.zip $HOME/go
|
|
|
|
one may run godoc as follows:
|
|
|
|
godoc -http=:6060 -zip=go.zip -goroot=$HOME/go
|
|
|
|
Godoc documentation is converted to HTML or to text using the go/doc package;
|
|
see http://golang.org/pkg/go/doc/#ToHTML for the exact rules.
|
|
See "Godoc: documenting Go code" for how to write good comments for godoc:
|
|
http://golang.org/doc/articles/godoc_documenting_go_code.html
|
|
|
|
*/
|
|
package main
|