...

Source file src/cmd/go/internal/doc/doc.go

Documentation: cmd/go/internal/doc

     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.
     6  package doc
     7  
     8  import (
     9  	"cmd/go/internal/base"
    10  	"cmd/go/internal/cfg"
    11  	"context"
    12  )
    13  
    14  var 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: `
    20  Doc prints the documentation comments associated with the item identified by its
    21  arguments (a package, const, func, type, var, method, or struct field)
    22  followed by a one-line summary of each of the first-level items "under"
    23  that item (package-level declarations for a package, methods for a type,
    24  etc.).
    25  
    26  Doc accepts zero, one, or two arguments.
    27  
    28  Given no arguments, that is, when run as
    29  
    30  	go doc
    31  
    32  it prints the package documentation for the package in the current directory.
    33  If the package is a command (package main), the exported symbols of the package
    34  are elided from the presentation unless the -cmd flag is provided.
    35  
    36  When run with one argument, the argument is treated as a Go-syntax-like
    37  representation of the item to be documented. What the argument selects depends
    38  on what is installed in GOROOT and GOPATH, as well as the form of the argument,
    39  which 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  
    46  The first item in this list matched by the argument is the one whose documentation
    47  is printed. (See the examples below.) However, if the argument starts with a capital
    48  letter it is assumed to identify a symbol or method in the current directory.
    49  
    50  For packages, the order of scanning is determined lexically in breadth-first order.
    51  That is, the package presented is the one that matches the search and is nearest
    52  the root and lexically first at its level of the hierarchy. The GOROOT tree is
    53  always scanned in its entirety before GOPATH.
    54  
    55  If there is no package specified or matched, the package in the current
    56  directory is selected, so "go doc Foo" shows the documentation for symbol Foo in
    57  the current package.
    58  
    59  The package path must be either a qualified path or a proper suffix of a
    60  path. The go tool's usual package mechanism does not apply: package path
    61  elements like . and ... are not implemented by go doc.
    62  
    63  When run with two arguments, the first is a package path (full path or suffix),
    64  and the second is a symbol, or symbol with method or struct field:
    65  
    66  	go doc <pkg> <sym>[.<methodOrField>]
    67  
    68  In all forms, when matching symbols, lower-case letters in the argument match
    69  either case but upper-case letters match exactly. This means that there may be
    70  multiple matches of a lower-case argument in a package if different symbols have
    71  different cases. If this occurs, documentation for all matches is printed.
    72  
    73  Examples:
    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  
   108  Flags:
   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  
   132  func runDoc(ctx context.Context, cmd *base.Command, args []string) {
   133  	base.Run(cfg.BuildToolexec, base.Tool("doc"), args)
   134  }
   135  

View as plain text