github.com/jhump/golang-x-tools@v0.0.0-20220218190644-4958d6d39439/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 -templates="" 56 directory containing alternate template files; if set, 57 the directory may provide alternative template files 58 for the files in $GOROOT/lib/godoc 59 -url=path 60 print to standard output the data that would be served by 61 an HTTP request for path 62 -zip="" 63 zip file providing the file system to serve; disabled if empty 64 65 By default, godoc looks at the packages it finds via $GOROOT and $GOPATH (if set). 66 This behavior can be altered by providing an alternative $GOROOT with the -goroot 67 flag. 68 69 When the -index flag is set, a search index is maintained. 70 The index is created at startup. 71 72 The index contains both identifier and full text search information (searchable 73 via regular expressions). The maximum number of full text search results shown 74 can be set with the -maxresults flag; if set to 0, no full text results are 75 shown, and only an identifier index but no full text search index is created. 76 77 By default, godoc uses the system's GOOS/GOARCH. You can provide the URL parameters 78 "GOOS" and "GOARCH" to set the output on the web page for the target system. 79 80 The presentation mode of web pages served by godoc can be controlled with the 81 "m" URL parameter; it accepts a comma-separated list of flag names as value: 82 83 all show documentation for all declarations, not just the exported ones 84 methods show all embedded methods, not just those of unexported anonymous fields 85 src show the original source code rather than the extracted documentation 86 flat present flat (not indented) directory listings using full paths 87 88 For instance, https://golang.org/pkg/math/big/?m=all shows the documentation 89 for all (not just the exported) declarations of package big. 90 91 By default, godoc serves files from the file system of the underlying OS. 92 Instead, a .zip file may be provided via the -zip flag, which contains 93 the file system to serve. The file paths stored in the .zip file must use 94 slash ('/') as path separator; and they must be unrooted. $GOROOT (or -goroot) 95 must be set to the .zip file directory path containing the Go root directory. 96 For instance, for a .zip file created by the command: 97 98 zip -r go.zip $HOME/go 99 100 one may run godoc as follows: 101 102 godoc -http=:6060 -zip=go.zip -goroot=$HOME/go 103 104 Godoc documentation is converted to HTML or to text using the go/doc package; 105 see https://golang.org/pkg/go/doc/#ToHTML for the exact rules. 106 Godoc also shows example code that is runnable by the testing package; 107 see https://golang.org/pkg/testing/#hdr-Examples for the conventions. 108 See "Godoc: documenting Go code" for how to write good comments for godoc: 109 https://golang.org/doc/articles/godoc_documenting_go_code.html 110 111 Deprecated: godoc cannot select what version of a package is displayed. 112 Instead, use golang.org/x/pkgsite/cmd/pkgsite. 113 */ 114 package main // import "github.com/jhump/golang-x-tools/cmd/godoc"