// 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 |