github.com/jgarto/itcv@v0.0.0-20180826224514-4eea09c1aa0d/_vendor/src/golang.org/x/tools/cmd/godoc/doc.go (about)

     1  // Copyright 2009 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  /*
     6  
     7  Godoc extracts and generates documentation for Go programs.
     8  
     9  It has two modes.
    10  
    11  Without the -http flag, it runs in command-line mode and prints plain text
    12  documentation to standard output and exits. If both a library package and
    13  a command with the same name exists, using the prefix cmd/ will force
    14  documentation on the command rather than the library package. If the -src
    15  flag is specified, godoc prints the exported interface of a package in Go
    16  source form, or the implementation of a specific exported language entity:
    17  
    18  	godoc fmt                # documentation for package fmt
    19  	godoc fmt Printf         # documentation for fmt.Printf
    20  	godoc cmd/go             # force documentation for the go command
    21  	godoc -src fmt           # fmt package interface in Go source form
    22  	godoc -src fmt Printf    # implementation of fmt.Printf
    23  
    24  In command-line mode, the -q flag enables search queries against a godoc running
    25  as a webserver. If no explicit server address is specified with the -server flag,
    26  godoc first tries localhost:6060 and then http://golang.org.
    27  
    28  	godoc -q Reader
    29  	godoc -q math.Sin
    30  	godoc -server=:6060 -q sin
    31  
    32  With the -http flag, it runs as a web server and presents the documentation as a
    33  web page.
    34  
    35  	godoc -http=:6060
    36  
    37  Usage:
    38  
    39  	godoc [flag] package [name ...]
    40  
    41  The flags are:
    42  
    43  	-v
    44  		verbose mode
    45  	-q
    46  		arguments are considered search queries: a legal query is a
    47  		single identifier (such as ToLower) or a qualified identifier
    48  		(such as math.Sin)
    49  	-src
    50  		print (exported) source in command-line mode
    51  	-tabwidth=4
    52  		width of tabs in units of spaces
    53  	-timestamps=true
    54  		show timestamps with directory listings
    55  	-index
    56  		enable identifier and full text search index
    57  		(no search box is shown if -index is not set)
    58  	-index_files=""
    59  		glob pattern specifying index files; if not empty,
    60  		the index is read from these files in sorted order
    61  	-index_throttle=0.75
    62  		index throttle value; a value of 0 means no time is allocated
    63  		to the indexer (the indexer will never finish), a value of 1.0
    64  		means that index creation is running at full throttle (other
    65  		goroutines may get no time while the index is built)
    66  	-links=true:
    67  		link identifiers to their declarations
    68  	-write_index=false
    69  		write index to a file; the file name must be specified with
    70  		-index_files
    71  	-maxresults=10000
    72  		maximum number of full text search results shown
    73  		(no full text index is built if maxresults <= 0)
    74  	-notes="BUG"
    75  		regular expression matching note markers to show
    76  		(e.g., "BUG|TODO", ".*")
    77  	-html
    78  		print HTML in command-line mode
    79  	-goroot=$GOROOT
    80  		Go root directory
    81  	-http=addr
    82  		HTTP service address (e.g., '127.0.0.1:6060' or just ':6060')
    83  	-server=addr
    84  		webserver address for command line searches
    85  	-analysis=type,pointer
    86  		comma-separated list of analyses to perform
    87  		"type": display identifier resolution, type info, method sets,
    88  			'implements', and static callees
    89  		"pointer": display channel peers, callers and dynamic callees
    90  			(significantly slower)
    91  		See http://golang.org/lib/godoc/analysis/help.html for details.
    92  	-templates=""
    93  		directory containing alternate template files; if set,
    94  		the directory may provide alternative template files
    95  		for the files in $GOROOT/lib/godoc
    96  	-url=path
    97  		print to standard output the data that would be served by
    98  		an HTTP request for path
    99  	-zip=""
   100  		zip file providing the file system to serve; disabled if empty
   101  
   102  By default, godoc looks at the packages it finds via $GOROOT and $GOPATH (if set).
   103  This behavior can be altered by providing an alternative $GOROOT with the -goroot
   104  flag.
   105  
   106  When godoc runs as a web server and -index is set, a search index is maintained.
   107  The index is created at startup.
   108  
   109  The index contains both identifier and full text search information (searchable
   110  via regular expressions). The maximum number of full text search results shown
   111  can be set with the -maxresults flag; if set to 0, no full text results are
   112  shown, and only an identifier index but no full text search index is created.
   113  
   114  By default, godoc uses the system's GOOS/GOARCH; in command-line mode you can
   115  set the GOOS/GOARCH environment variables to get output for the system specified.
   116  If -http was specified you can provide the URL parameters "GOOS" and "GOARCH"
   117  to set the output on the web page.
   118  
   119  The presentation mode of web pages served by godoc can be controlled with the
   120  "m" URL parameter; it accepts a comma-separated list of flag names as value:
   121  
   122  	all	show documentation for all declarations, not just the exported ones
   123  	methods	show all embedded methods, not just those of unexported anonymous fields
   124  	src	show the original source code rather then the extracted documentation
   125  	text	present the page in textual (command-line) form rather than HTML
   126  	flat	present flat (not indented) directory listings using full paths
   127  
   128  For instance, http://golang.org/pkg/math/big/?m=all,text shows the documentation
   129  for all (not just the exported) declarations of package big, in textual form (as
   130  it would appear when using godoc from the command line: "godoc -src math/big .*").
   131  
   132  By default, godoc serves files from the file system of the underlying OS.
   133  Instead, a .zip file may be provided via the -zip flag, which contains
   134  the file system to serve. The file paths stored in the .zip file must use
   135  slash ('/') as path separator; and they must be unrooted. $GOROOT (or -goroot)
   136  must be set to the .zip file directory path containing the Go root directory.
   137  For instance, for a .zip file created by the command:
   138  
   139  	zip -r go.zip $HOME/go
   140  
   141  one may run godoc as follows:
   142  
   143  	godoc -http=:6060 -zip=go.zip -goroot=$HOME/go
   144  
   145  Godoc documentation is converted to HTML or to text using the go/doc package;
   146  see http://golang.org/pkg/go/doc/#ToHTML for the exact rules.
   147  Godoc also shows example code that is runnable by the testing package;
   148  see http://golang.org/pkg/testing/#hdr-Examples for the conventions.
   149  See "Godoc: documenting Go code" for how to write good comments for godoc:
   150  http://golang.org/doc/articles/godoc_documenting_go_code.html
   151  
   152  */
   153  package main // import "golang.org/x/tools/cmd/godoc"