version: 1.10

package doc

import "go/doc"

Overview

Package doc extracts source code documentation from a Go AST.

Index

Package files

comment.go doc.go example.go exports.go filter.go reader.go synopsis.go

Variables

  1. var IllegalPrefixes = []string{
  2.     "copyright",
  3.     "all rights",
  4.     "author",
  5. }

func Examples 

  1. func Examples(files ...*ast.File) []*Example

Examples returns the examples found in the files, sorted by Name field. The Order fields record the order in which the examples were encountered.

Playable Examples must be in a package whose name ends in “_test”. An Example is “playable” (the Play field is non-nil) in either of these circumstances:

  1. - The example function is self-contained: the function references only
  2.   identifiers from other packages (or predeclared identifiers, such as
  3.   "int") and the test file does not include a dot import.
  4. - The entire test file is the example: the file contains exactly one
  5.   example function, zero test or benchmark functions, and at least one
  6.   top-level function, type, variable, or constant declaration other
  7.   than the example function.

func IsPredeclared 

  1. func IsPredeclared(s string) bool

IsPredeclared reports whether s is a predeclared identifier.

func Synopsis 

  1. func Synopsis(s string) string

Synopsis returns a cleaned version of the first sentence in s. That sentence ends after the first period followed by space and not preceded by exactly one uppercase letter. The result string has no \n, \r, or \t characters and uses only single spaces between words. If s starts with any of the IllegalPrefixes, the result is the empty string.

func ToHTML 

  1. func ToHTML(w io.Writer, text string, words map[string]string)

ToHTML converts comment text to formatted HTML. The comment was prepared by DocReader, so it is known not to have leading, trailing blank lines nor to have trailing spaces at the end of lines. The comment markers have already been removed.

Each span of unindented non-blank lines is converted into a single paragraph. There is one exception to the rule: a span that consists of a single line, is followed by another paragraph span, begins with a capital letter, and contains no punctuation is formatted as a heading.

A span of indented lines is converted into a 

  1.  block, with the common indent
  2. prefix removed.
  3. URLs in the comment text are converted into links; if the URL also appears in
  4. the words map, the link is taken from the map (if the corresponding map value is
  5. the empty string, the URL is not converted into a link).
  6. Go identifiers that appear in the words map are italicized; if the corresponding
  7. map value is not the empty string, it is considered a URL and the word is
  8. converted into a link.
  9. func ToText
  10.     
  11. func ToText(w io.Writer, text string, indent, preIndent string, width int)
  12.  
  13. ToText prepares comment text for presentation in textual output. It wraps
  14. paragraphs of text to width or fewer Unicode code points and then prefixes each
  15. line with the indent. In preformatted sections (such as program text), it
  16. prefixes each non-blank line with preIndent.
  17. type Example
  18.     
  19. type Example struct {
  20.     Name        string // name of the item being exemplified
  21.     Doc         string // example function doc string
  22.     Code        ast.Node
  23.     Play        *ast.File // a whole program version of the example
  24.     Comments    []*ast.CommentGroup
  25.     Output      string // expected output
  26.     Unordered   bool
  27.     EmptyOutput bool // expect empty output
  28.     Order       int  // original source code order
  29. }
  30.  
  31. An Example represents an example function found in a source files.
  32. type Filter
  33.     
  34. type Filter func(string) bool
  35.  
  36.  
  37. type Func
  38.     
  39. type Func struct {
  40.     Doc  string
  41.     Name string
  42.     Decl *ast.FuncDecl
  44.     // methods
  45.     // (for functions, these fields have the respective zero value)
  46.     Recv  string // actual   receiver "T" or "*T"
  47.     Orig  string // original receiver "T" or "*T"
  48.     Level int    // embedding level; 0 means not embedded
  49. }
  50.  
  51. Func is the documentation for a func declaration.
  52. type Mode
  53.     
  54. type Mode int
  55.  
  56. Mode values control the operation of New.
  57. const (
  58.     // extract documentation for all package-level declarations,
  59.     // not just exported ones
  60.     AllDecls Mode = 1 << iota
  62.     // show all embedded methods, not just the ones of
  63.     // invisible (unexported) anonymous fields
  64.     AllMethods
  65. )
  66.  
  67.  
  68. type Note
  69.     
  70. type Note struct {
  71.     Pos, End token.Pos // position range of the comment containing the marker
  72.     UID      string    // uid found with the marker
  73.     Body     string    // note body text
  74. }
  75.  
  76. A Note represents a marked comment starting with “MARKER(uid): note body”. Any
  77. note with a marker of 2 or more upper case [A-Z] letters and a uid of at least
  78. one character is recognized. The “:” following the uid is optional. Notes are
  79. collected in the Package.Notes map indexed by the notes marker.
  80. type Package
  81.     
  82. type Package struct {
  83.     Doc        string
  84.     Name       string
  85.     ImportPath string
  86.     Imports    []string
  87.     Filenames  []string
  88.     Notes      map[string][]*Note
  90.     // Deprecated: For backward compatibility Bugs is still populated,
  91.     // but all new code should use Notes instead.
  92.     Bugs []string
  94.     // declarations
  95.     Consts []*Value
  96.     Types  []*Type
  97.     Vars   []*Value
  98.     Funcs  []*Func
  99. }
  100.  
  101. Package is the documentation for an entire package.
  102. func New
  103.     
  104. func New(pkg *ast.Package, importPath string, mode Mode) *Package
  105.  
  106. New computes the package documentation for the given package AST. New takes
  107. ownership of the AST pkg and may edit or overwrite it.
  108. func (*Package) Filter
  109.     
  110. func (p *Package) Filter(f Filter)
  111.  
  112. Filter eliminates documentation for names that don’t pass through the filter f.
  113. TODO(gri): Recognize “Type.Method” as a name.
  114. type Type
  115.     
  116. type Type struct {
  117.     Doc  string
  118.     Name string
  119.     Decl *ast.GenDecl
  121.     // associated declarations
  122.     Consts  []*Value // sorted list of constants of (mostly) this type
  123.     Vars    []*Value // sorted list of variables of (mostly) this type
  124.     Funcs   []*Func  // sorted list of functions returning this type
  125.     Methods []*Func  // sorted list of methods (including embedded ones) of this type
  126. }
  127.  
  128. Type is the documentation for a type declaration.
  129. type Value
  130.     
  131. type Value struct {
  132.     Doc   string
  133.     Names []string // var or const names in declaration order
  134.     Decl  *ast.GenDecl
  135.     // contains filtered or unexported fields
  136. }
  137.  
  138. Value is the documentation for a (possibly grouped) var or const declaration.