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