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 main 6 7 var cmdDoc = &Command{ 8 Run: runDoc, 9 UsageLine: "doc [-u] [-c] [package|[package.]symbol[.method]]", 10 CustomFlags: true, 11 Short: "show documentation for package or symbol", 12 Long: ` 13 Doc prints the documentation comments associated with the item identified by its 14 arguments (a package, const, func, type, var, or method) followed by a one-line 15 summary of each of the first-level items "under" that item (package-level 16 declarations for a package, methods for a type, etc.). 17 18 Doc accepts zero, one, or two arguments. 19 20 Given no arguments, that is, when run as 21 22 go doc 23 24 it prints the package documentation for the package in the current directory. 25 If the package is a command (package main), the exported symbols of the package 26 are elided from the presentation unless the -cmd flag is provided. 27 28 When run with one argument, the argument is treated as a Go-syntax-like 29 representation of the item to be documented. What the argument selects depends 30 on what is installed in GOROOT and GOPATH, as well as the form of the argument, 31 which is schematically one of these: 32 33 go doc <pkg> 34 go doc <sym>[.<method>] 35 go doc [<pkg>].<sym>[.<method>] 36 37 The first item in this list matched by the argument is the one whose 38 documentation is printed. (See the examples below.) For packages, the order of 39 scanning is determined lexically, but the GOROOT tree is always scanned before 40 GOPATH. 41 42 If there is no package specified or matched, the package in the current 43 directory is selected, so "go doc Foo" shows the documentation for symbol Foo in 44 the current package. 45 46 The package path must be either a qualified path or a proper suffix of a 47 path. The go tool's usual package mechanism does not apply: package path 48 elements like . and ... are not implemented by go doc. 49 50 When run with two arguments, the first must be a full package path (not just a 51 suffix), and the second is a symbol or symbol and method; this is similar to the 52 syntax accepted by godoc: 53 54 go doc <pkg> <sym>[.<method>] 55 56 In all forms, when matching symbols, lower-case letters in the argument match 57 either case but upper-case letters match exactly. This means that there may be 58 multiple matches of a lower-case argument in a package if different symbols have 59 different cases. If this occurs, documentation for all matches is printed. 60 61 Examples: 62 go doc 63 Show documentation for current package. 64 go doc Foo 65 Show documentation for Foo in the current package. 66 (Foo starts with a capital letter so it cannot match 67 a package path.) 68 go doc encoding/json 69 Show documentation for the encoding/json package. 70 go doc json 71 Shorthand for encoding/json. 72 go doc json.Number (or go doc json.number) 73 Show documentation and method summary for json.Number. 74 go doc json.Number.Int64 (or go doc json.number.int64) 75 Show documentation for json.Number's Int64 method. 76 go doc cmd/doc 77 Show package docs for the doc command. 78 go doc -cmd cmd/doc 79 Show package docs and exported symbols within the doc command. 80 go doc template.new 81 Show documentation for html/template's New function. 82 (html/template is lexically before text/template) 83 go doc text/template.new # One argument 84 Show documentation for text/template's New function. 85 go doc text/template new # Two arguments 86 Show documentation for text/template's New function. 87 88 Flags: 89 -c 90 Respect case when matching symbols. 91 -cmd 92 Treat a command (package main) like a regular package. 93 Otherwise package main's exported symbols are hidden 94 when showing the package's top-level documentation. 95 -u 96 Show documentation for unexported as well as exported 97 symbols and methods. 98 `, 99 } 100 101 func runDoc(cmd *Command, args []string) { 102 run(buildToolExec, tool("doc"), args) 103 } 104
