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