GODOC(1)						      General Commands Manual							  GODOC(1)

NAME

       godoc - extracts and generates documentation for Go programs

SYNOPSIS

       godoc [flag] command [ name ...	]

DESCRIPTION

       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

       By  default,  godoc  looks at the packages it finds via $GOROOT and $GOPATH (if set). Additional directories may be specified via the -path
       flag which accepts a list of colon-separated paths; unrooted paths are relative to the current working directory. Each path  is	considered
       as  an  additional  root  for  packages	in  order  of appearance. The last (absolute) path element is the prefix for the package path. For
       instance, given the flag value:

	     path=".:/home/bar:/public"

       for a godoc started in /home/user/godoc, absolute paths are mapped to package paths as follows:

	     /home/user/godoc/x -> godoc/x
	     /home/bar/x	-> bar/x
	     /public/x		-> public/x

       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

       See "Godoc: documenting Go code" for how to write good comments for godoc: http://golang.org/doc/articles/godoc_documenting_go_code.html

OPTIONS

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

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

       -path=""
	      additional package directories (colon-separated)

       -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

       -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

AUTHOR

       This manual page was written by Michael Stapelberg <stapelberg@debian.org>, for the Debian project (and may be used by others).

								    2012-05-13								  GODOC(1)