github.com/mdempsky/go@v0.0.0-20151201204031-5dd372bd1e70/src/cmd/go/doc.go (about)

     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  	go doc [<pkg>.][<sym>.]<method>
    37  
    38  The first item in this list matched by the argument is the one whose documentation
    39  is printed. (See the examples below.) However, if the argument starts with a capital
    40  letter it is assumed to identify a symbol or method in the current directory.
    41  
    42  For packages, the order of scanning is determined lexically, but the GOROOT tree
    43  is always scanned before GOPATH.
    44  
    45  If there is no package specified or matched, the package in the current
    46  directory is selected, so "go doc Foo" shows the documentation for symbol Foo in
    47  the current package.
    48  
    49  The package path must be either a qualified path or a proper suffix of a
    50  path. The go tool's usual package mechanism does not apply: package path
    51  elements like . and ... are not implemented by go doc.
    52  
    53  When run with two arguments, the first must be a full package path (not just a
    54  suffix), and the second is a symbol or symbol and method; this is similar to the
    55  syntax accepted by godoc:
    56  
    57  	go doc <pkg> <sym>[.<method>]
    58  
    59  In all forms, when matching symbols, lower-case letters in the argument match
    60  either case but upper-case letters match exactly. This means that there may be
    61  multiple matches of a lower-case argument in a package if different symbols have
    62  different cases. If this occurs, documentation for all matches is printed.
    63  
    64  Examples:
    65  	go doc
    66  		Show documentation for current package.
    67  	go doc Foo
    68  		Show documentation for Foo in the current package.
    69  		(Foo starts with a capital letter so it cannot match
    70  		a package path.)
    71  	go doc encoding/json
    72  		Show documentation for the encoding/json package.
    73  	go doc json
    74  		Shorthand for encoding/json.
    75  	go doc json.Number (or go doc json.number)
    76  		Show documentation and method summary for json.Number.
    77  	go doc json.Number.Int64 (or go doc json.number.int64)
    78  		Show documentation for json.Number's Int64 method.
    79  	go doc cmd/doc
    80  		Show package docs for the doc command.
    81  	go doc -cmd cmd/doc
    82  		Show package docs and exported symbols within the doc command.
    83  	go doc template.new
    84  		Show documentation for html/template's New function.
    85  		(html/template is lexically before text/template)
    86  	go doc text/template.new # One argument
    87  		Show documentation for text/template's New function.
    88  	go doc text/template new # Two arguments
    89  		Show documentation for text/template's New function.
    90  
    91  	At least in the current tree, these invocations all print the
    92  	documentation for json.Decoder's Decode method:
    93  
    94  	go doc json.Decoder.Decode
    95  	go doc json.decoder.decode
    96  	go doc json.decode
    97  	cd go/src/encoding/json; go doc decode
    98  
    99  Flags:
   100  	-c
   101  		Respect case when matching symbols.
   102  	-cmd
   103  		Treat a command (package main) like a regular package.
   104  		Otherwise package main's exported symbols are hidden
   105  		when showing the package's top-level documentation.
   106  	-u
   107  		Show documentation for unexported as well as exported
   108  		symbols and methods.
   109  `,
   110  }
   111  
   112  func runDoc(cmd *Command, args []string) {
   113  	run(buildToolExec, tool("doc"), args)
   114  }