libgo/go/cmd/go/internal/doc/doc.go

   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 )
  12
  13 var CmdDoc = &base.Command{
  14         Run:         runDoc,
  15         UsageLine:   "doc [-u] [-c] [package|[package.]symbol[.methodOrField]]",
  16         CustomFlags: true,
  17         Short:       "show documentation for package or symbol",
  18         Long: `
  19 Doc prints the documentation comments associated with the item identified by its
  20 arguments (a package, const, func, type, var, method, or struct field)
  21 followed by a one-line summary of each of the first-level items "under"
  22 that item (package-level declarations for a package, methods for a type,
  23 etc.).
  24
  25 Doc accepts zero, one, or two arguments.
  26
  27 Given no arguments, that is, when run as
  28
  29         go doc
  30
  31 it prints the package documentation for the package in the current directory.
  32 If the package is a command (package main), the exported symbols of the package
  33 are elided from the presentation unless the -cmd flag is provided.
  34
  35 When run with one argument, the argument is treated as a Go-syntax-like
  36 representation of the item to be documented. What the argument selects depends
  37 on what is installed in GOROOT and GOPATH, as well as the form of the argument,
  38 which is schematically one of these:
  39
  40         go doc <pkg>
  41         go doc <sym>[.<methodOrField>]
  42         go doc [<pkg>.]<sym>[.<methodOrField>]
  43         go doc [<pkg>.][<sym>.]<methodOrField>
  44
  45 The first item in this list matched by the argument is the one whose documentation
  46 is printed. (See the examples below.) However, if the argument starts with a capital
  47 letter it is assumed to identify a symbol or method in the current directory.
  48
  49 For packages, the order of scanning is determined lexically in breadth-first order.
  50 That is, the package presented is the one that matches the search and is nearest
  51 the root and lexically first at its level of the hierarchy. The GOROOT tree is
  52 always scanned in its entirety before GOPATH.
  53
  54 If there is no package specified or matched, the package in the current
  55 directory is selected, so "go doc Foo" shows the documentation for symbol Foo in
  56 the current package.
  57
  58 The package path must be either a qualified path or a proper suffix of a
  59 path. The go tool's usual package mechanism does not apply: package path
  60 elements like . and ... are not implemented by go doc.
  61
  62 When run with two arguments, the first must be a full package path (not just a
  63 suffix), and the second is a symbol, or symbol with method or struct field.
  64 This is similar to the syntax accepted by godoc:
  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         -c
 110                 Respect case when matching symbols.
 111         -cmd
 112                 Treat a command (package main) like a regular package.
 113                 Otherwise package main's exported symbols are hidden
 114                 when showing the package's top-level documentation.
 115         -u
 116                 Show documentation for unexported as well as exported
 117                 symbols, methods, and fields.
 118 `,
 119 }
 120
 121 func runDoc(cmd *base.Command, args []string) {
 122         base.Run(cfg.BuildToolexec, base.Tool("doc"), args)
 123 }