github.com/april1989/origin-go-tools@v0.0.32/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 runs as a web server and presents the documentation as a
    10  web page.
    11  
    12  	godoc -http=:6060
    13  
    14  Usage:
    15  
    16  	godoc [flag]
    17  
    18  The flags are:
    19  
    20  	-v
    21  		verbose mode
    22  	-timestamps=true
    23  		show timestamps with directory listings
    24  	-index
    25  		enable identifier and full text search index
    26  		(no search box is shown if -index is not set)
    27  	-index_files=""
    28  		glob pattern specifying index files; if not empty,
    29  		the index is read from these files in sorted order
    30  	-index_throttle=0.75
    31  		index throttle value; a value of 0 means no time is allocated
    32  		to the indexer (the indexer will never finish), a value of 1.0
    33  		means that index creation is running at full throttle (other
    34  		goroutines may get no time while the index is built)
    35  	-index_interval=0
    36  		interval of indexing; a value of 0 sets it to 5 minutes, a
    37  		negative value indexes only once at startup
    38  	-play=false
    39  		enable playground
    40  	-links=true
    41  		link identifiers to their declarations
    42  	-write_index=false
    43  		write index to a file; the file name must be specified with
    44  		-index_files
    45  	-maxresults=10000
    46  		maximum number of full text search results shown
    47  		(no full text index is built if maxresults <= 0)
    48  	-notes="BUG"
    49  		regular expression matching note markers to show
    50  		(e.g., "BUG|TODO", ".*")
    51  	-goroot=$GOROOT
    52  		Go root directory
    53  	-http=addr
    54  		HTTP service address (e.g., '127.0.0.1:6060' or just ':6060')
    55  	-analysis=type,pointer
    56  		comma-separated list of analyses to perform
    57  		"type": display identifier resolution, type info, method sets,
    58  			'implements', and static callees
    59  		"pointer": display channel peers, callers and dynamic callees
    60  			(significantly slower)
    61  		See https://golang.org/lib/godoc/analysis/help.html for details.
    62  	-templates=""
    63  		directory containing alternate template files; if set,
    64  		the directory may provide alternative template files
    65  		for the files in $GOROOT/lib/godoc
    66  	-url=path
    67  		print to standard output the data that would be served by
    68  		an HTTP request for path
    69  	-zip=""
    70  		zip file providing the file system to serve; disabled if empty
    71  
    72  By default, godoc looks at the packages it finds via $GOROOT and $GOPATH (if set).
    73  This behavior can be altered by providing an alternative $GOROOT with the -goroot
    74  flag.
    75  
    76  When the -index flag is set, a search index is maintained.
    77  The index is created at startup.
    78  
    79  The index contains both identifier and full text search information (searchable
    80  via regular expressions). The maximum number of full text search results shown
    81  can be set with the -maxresults flag; if set to 0, no full text results are
    82  shown, and only an identifier index but no full text search index is created.
    83  
    84  By default, godoc uses the system's GOOS/GOARCH. You can provide the URL parameters
    85  "GOOS" and "GOARCH" to set the output on the web page for the target system.
    86  
    87  The presentation mode of web pages served by godoc can be controlled with the
    88  "m" URL parameter; it accepts a comma-separated list of flag names as value:
    89  
    90  	all	show documentation for all declarations, not just the exported ones
    91  	methods	show all embedded methods, not just those of unexported anonymous fields
    92  	src	show the original source code rather than the extracted documentation
    93  	flat	present flat (not indented) directory listings using full paths
    94  
    95  For instance, https://golang.org/pkg/math/big/?m=all shows the documentation
    96  for all (not just the exported) declarations of package big.
    97  
    98  By default, godoc serves files from the file system of the underlying OS.
    99  Instead, a .zip file may be provided via the -zip flag, which contains
   100  the file system to serve. The file paths stored in the .zip file must use
   101  slash ('/') as path separator; and they must be unrooted. $GOROOT (or -goroot)
   102  must be set to the .zip file directory path containing the Go root directory.
   103  For instance, for a .zip file created by the command:
   104  
   105  	zip -r go.zip $HOME/go
   106  
   107  one may run godoc as follows:
   108  
   109  	godoc -http=:6060 -zip=go.zip -goroot=$HOME/go
   110  
   111  Godoc documentation is converted to HTML or to text using the go/doc package;
   112  see https://golang.org/pkg/go/doc/#ToHTML for the exact rules.
   113  Godoc also shows example code that is runnable by the golibexec_testing package;
   114  see https://golang.org/pkg/testing/#hdr-Examples for the conventions.
   115  See "Godoc: documenting Go code" for how to write good comments for godoc:
   116  https://golang.org/doc/articles/godoc_documenting_go_code.html
   117  
   118  */
   119  package main // import "github.com/april1989/origin-go-tools/cmd/godoc"