Documentation

Overview

    Package doc extracts source code documentation from a Go AST.

    Index

    Examples

    Constants

    This section is empty.

    Variables

    View Source
    var IllegalPrefixes = []string{
    	"copyright",
    	"all rights",
    	"author",
    }

    Functions

    func IsPredeclared added in go1.8

    func IsPredeclared(s string) bool

      IsPredeclared reports whether s is a predeclared identifier.

      func Synopsis

      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

        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 other than parentheses and commas is formatted as a heading.

          A span of indented lines is converted into a <pre> block, with the common indent prefix removed.

          URLs in the comment text are converted into links; if the URL also appears in the words map, the link is taken from the map (if the corresponding map value is the empty string, the URL is not converted into a link).

          A pair of (consecutive) backticks (`) is converted to a unicode left quote (“), and a pair of (consecutive) single quotes (') is converted to a unicode right quote (”).

          Go identifiers that appear in the words map are italicized; if the corresponding map value is not the empty string, it is considered a URL and the word is converted into a link.

          func ToText

          func ToText(w io.Writer, text string, indent, preIndent string, width int)

            ToText prepares comment text for presentation in textual output. It wraps paragraphs of text to width or fewer Unicode code points and then prefixes each line with the indent. In preformatted sections (such as program text), it prefixes each non-blank line with preIndent.

            A pair of (consecutive) backticks (`) is converted to a unicode left quote (“), and a pair of (consecutive) single quotes (') is converted to a unicode right quote (”).

            Types

            type Example

            type Example struct {
            	Name        string // name of the item being exemplified (including optional suffix)
            	Suffix      string // example suffix, without leading '_' (only populated by NewFromFiles)
            	Doc         string // example function doc string
            	Code        ast.Node
            	Play        *ast.File // a whole program version of the example
            	Comments    []*ast.CommentGroup
            	Output      string // expected output
            	Unordered   bool
            	EmptyOutput bool // expect empty output
            	Order       int  // original source code order
            }

              An Example represents an example function found in a test source file.

              func Examples

              func Examples(testFiles ...*ast.File) []*Example

                Examples returns the examples found in testFiles, sorted by Name field. The Order fields record the order in which the examples were encountered. The Suffix field is not populated when Examples is called directly, it is only populated by NewFromFiles for examples it finds in _test.go files.

                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:

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

                type Filter

                type Filter func(string) bool

                type Func

                type Func struct {
                	Doc  string
                	Name string
                	Decl *ast.FuncDecl
                
                	// methods
                	// (for functions, these fields have the respective zero value)
                	Recv  string // actual   receiver "T" or "*T"
                	Orig  string // original receiver "T" or "*T"
                	Level int    // embedding level; 0 means not embedded
                
                	// Examples is a sorted list of examples associated with this
                	// function or method. Examples are extracted from _test.go files
                	// provided to NewFromFiles.
                	Examples []*Example
                }

                  Func is the documentation for a func declaration.

                  type Mode

                  type Mode int

                    Mode values control the operation of New and NewFromFiles.

                    const (
                    	// AllDecls says to extract documentation for all package-level
                    	// declarations, not just exported ones.
                    	AllDecls Mode = 1 << iota
                    
                    	// AllMethods says to show all embedded methods, not just the ones of
                    	// invisible (unexported) anonymous fields.
                    	AllMethods
                    
                    	// PreserveAST says to leave the AST unmodified. Originally, pieces of
                    	// the AST such as function bodies were nil-ed out to save memory in
                    	// godoc, but not all programs want that behavior.
                    	PreserveAST
                    )

                    type Note added in go1.1

                    type Note struct {
                    	Pos, End token.Pos // position range of the comment containing the marker
                    	UID      string    // uid found with the marker
                    	Body     string    // note body text
                    }

                      A Note represents a marked comment starting with "MARKER(uid): note body". Any note with a marker of 2 or more upper case [A-Z] letters and a uid of at least one character is recognized. The ":" following the uid is optional. Notes are collected in the Package.Notes map indexed by the notes marker.

                      type Package

                      type Package struct {
                      	Doc        string
                      	Name       string
                      	ImportPath string
                      	Imports    []string
                      	Filenames  []string
                      	Notes      map[string][]*Note
                      
                      	// Deprecated: For backward compatibility Bugs is still populated,
                      	// but all new code should use Notes instead.
                      	Bugs []string
                      
                      	// declarations
                      	Consts []*Value
                      	Types  []*Type
                      	Vars   []*Value
                      	Funcs  []*Func
                      
                      	// Examples is a sorted list of examples associated with
                      	// the package. Examples are extracted from _test.go files
                      	// provided to NewFromFiles.
                      	Examples []*Example
                      }

                        Package is the documentation for an entire package.

                        func New

                        func New(pkg *ast.Package, importPath string, mode Mode) *Package

                          New computes the package documentation for the given package AST. New takes ownership of the AST pkg and may edit or overwrite it. To have the Examples fields populated, use NewFromFiles and include the package's _test.go files.

                          func NewFromFiles added in go1.14

                          func NewFromFiles(fset *token.FileSet, files []*ast.File, importPath string, opts ...interface{}) (*Package, error)

                            NewFromFiles computes documentation for a package.

                            The package is specified by a list of *ast.Files and corresponding file set, which must not be nil. NewFromFiles uses all provided files when computing documentation, so it is the caller's responsibility to provide only the files that match the desired build context. "go/build".Context.MatchFile can be used for determining whether a file matches a build context with the desired GOOS and GOARCH values, and other build constraints. The import path of the package is specified by importPath.

                            Examples found in _test.go files are associated with the corresponding type, function, method, or the package, based on their name. If the example has a suffix in its name, it is set in the Example.Suffix field. Examples with malformed names are skipped.

                            Optionally, a single extra argument of type Mode can be provided to control low-level aspects of the documentation extraction behavior.

                            NewFromFiles takes ownership of the AST files and may edit them, unless the PreserveAST Mode bit is on.

                            Example

                              This example illustrates how to use NewFromFiles to compute package documentation with examples.

                              Output:
                              
                              package p - This is the package comment.
                              func Greet - This comment is associated with the Greet function.
                               ⤷ example with suffix "world" - This comment is associated with the ExampleGreet_world example.
                              

                              func (*Package) Filter

                              func (p *Package) Filter(f Filter)

                                Filter eliminates documentation for names that don't pass through the filter f. TODO(gri): Recognize "Type.Method" as a name.

                                type Type

                                type Type struct {
                                	Doc  string
                                	Name string
                                	Decl *ast.GenDecl
                                
                                	// associated declarations
                                	Consts  []*Value // sorted list of constants of (mostly) this type
                                	Vars    []*Value // sorted list of variables of (mostly) this type
                                	Funcs   []*Func  // sorted list of functions returning this type
                                	Methods []*Func  // sorted list of methods (including embedded ones) of this type
                                
                                	// Examples is a sorted list of examples associated with
                                	// this type. Examples are extracted from _test.go files
                                	// provided to NewFromFiles.
                                	Examples []*Example
                                }

                                  Type is the documentation for a type declaration.

                                  type Value

                                  type Value struct {
                                  	Doc   string
                                  	Names []string // var or const names in declaration order
                                  	Decl  *ast.GenDecl
                                  	// contains filtered or unexported fields
                                  }

                                    Value is the documentation for a (possibly grouped) var or const declaration.