1
2
3
4
5
6
7
8 package doc
9
10 import (
11 "cmd/go/internal/base"
12 "cmd/internal/doc"
13 "context"
14 )
15
16 var CmdDoc = &base.Command{
17 Run: runDoc,
18 UsageLine: "go doc [doc flags] [package|[package.]symbol[.methodOrField]]",
19 CustomFlags: true,
20 Short: "show documentation for package or symbol",
21 Long: `
22 Doc prints the documentation comments associated with the item identified by its
23 arguments (a package, const, func, type, var, method, or struct field)
24 followed by a one-line summary of each of the first-level items "under"
25 that item (package-level declarations for a package, methods for a type,
26 etc.).
27
28 Doc accepts zero, one, or two arguments.
29
30 Given no arguments, that is, when run as
31
32 go doc
33
34 it prints the package documentation for the package in the current directory.
35 If the package is a command (package main), the exported symbols of the package
36 are elided from the presentation unless the -cmd flag is provided.
37
38 When run with one argument, the argument is treated as a Go-syntax-like
39 representation of the item to be documented. What the argument selects depends
40 on what is installed in GOROOT and GOPATH, as well as the form of the argument,
41 which is schematically one of these:
42
43 go doc <pkg>
44 go doc <sym>[.<methodOrField>]
45 go doc [<pkg>.]<sym>[.<methodOrField>]
46 go doc [<pkg>.][<sym>.]<methodOrField>
47
48 The first item in this list matched by the argument is the one whose documentation
49 is printed. (See the examples below.) However, if the argument starts with a capital
50 letter it is assumed to identify a symbol or method in the current directory.
51
52 For packages, the order of scanning is determined lexically in breadth-first order.
53 That is, the package presented is the one that matches the search and is nearest
54 the root and lexically first at its level of the hierarchy. The GOROOT tree is
55 always scanned in its entirety before GOPATH.
56
57 If there is no package specified or matched, the package in the current
58 directory is selected, so "go doc Foo" shows the documentation for symbol Foo in
59 the current package.
60
61 The package path must be either a qualified path or a proper suffix of a
62 path. The go tool's usual package mechanism does not apply: package path
63 elements like . and ... are not implemented by go doc.
64
65 When run with two arguments, the first is a package path (full path or suffix),
66 and the second is a symbol, or symbol with method or struct field:
67
68 go doc <pkg> <sym>[.<methodOrField>]
69
70 In all forms, when matching symbols, lower-case letters in the argument match
71 either case but upper-case letters match exactly. This means that there may be
72 multiple matches of a lower-case argument in a package if different symbols have
73 different cases. If this occurs, documentation for all matches is printed.
74
75 Examples:
76 go doc
77 Show documentation for current package.
78 go doc -http
79 Serve HTML documentation over HTTP for the current package.
80 go doc Foo
81 Show documentation for Foo in the current package.
82 (Foo starts with a capital letter so it cannot match
83 a package path.)
84 go doc encoding/json
85 Show documentation for the encoding/json package.
86 go doc json
87 Shorthand for encoding/json.
88 go doc json.Number (or go doc json.number)
89 Show documentation and method summary for json.Number.
90 go doc json.Number.Int64 (or go doc json.number.int64)
91 Show documentation for json.Number's Int64 method.
92 go doc cmd/doc
93 Show package docs for the doc command.
94 go doc -cmd cmd/doc
95 Show package docs and exported symbols within the doc command.
96 go doc template.new
97 Show documentation for html/template's New function.
98 (html/template is lexically before text/template)
99 go doc text/template.new # One argument
100 Show documentation for text/template's New function.
101 go doc text/template new # Two arguments
102 Show documentation for text/template's New function.
103
104 At least in the current tree, these invocations all print the
105 documentation for json.Decoder's Decode method:
106
107 go doc json.Decoder.Decode
108 go doc json.decoder.decode
109 go doc json.decode
110 cd go/src/encoding/json; go doc decode
111
112 Flags:
113 -all
114 Show all the documentation for the package.
115 -c
116 Respect case when matching symbols.
117 -cmd
118 Treat a command (package main) like a regular package.
119 Otherwise package main's exported symbols are hidden
120 when showing the package's top-level documentation.
121 -http
122 Serve HTML docs over HTTP.
123 -short
124 One-line representation for each symbol.
125 -src
126 Show the full source code for the symbol. This will
127 display the full Go source of its declaration and
128 definition, such as a function definition (including
129 the body), type declaration or enclosing const
130 block. The output may therefore include unexported
131 details.
132 -u
133 Show documentation for unexported as well as exported
134 symbols, methods, and fields.
135 `,
136 }
137
138 func runDoc(ctx context.Context, cmd *base.Command, args []string) {
139 doc.Main(args)
140 }
141
View as plain text