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