Overview

Package doc extracts source code documentation from a Go AST.

Index

• Variables
• func IsPredeclared(s string) bool
• func ToHTML(w io.Writer, text string, words map[string]string)
• type Example
• type Func
• type Note
• • func New(pkg ast.Package, importPath string, mode Mode) Package
• type Type

comment.go example.go filter.go synopsis.go

Variables

func
¶

func Examples(files ...*.File) []*

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:

- The example function is self-contained: the function references only
  "int") and the test file does not include a dot import.
  example function, zero test or benchmark functions, and at least one
  than the example function.

func IsPredeclared(s string) 

IsPredeclared reports whether s is a predeclared identifier.

func Synopsis

func Synopsis(s 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., text string, words map[]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.

 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).
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 
    ¶
func ToText(w .Writer, text , indent, preIndent string, width )
 
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.
type Example
    
type Example struct {
    Name        string // name of the item being exemplified
    Doc          // example function doc string
    Code        ast.
    Play        *ast. // a whole program version of the example
    Comments    []*ast.
    Output      string // expected output
    Unordered   
    EmptyOutput bool // expect empty output
}
 
An Example represents an example function found in a source files.
type Filter func() bool
 
 
type 
    ¶
type Func struct {
    Doc  
    Name string
    Decl *.FuncDecl
    // methods
    // (for functions, these fields have the respective zero value)
    Orig   // original receiver "T" or "*T"
    Level int    // embedding level; 0 means not embedded
}
 
Func is the documentation for a func declaration.
type 
    ¶
type Mode 
 
Mode values control the operation of New.
const (
    // extract documentation for all package-level declarations,
    // not just exported ones
    AllDecls Mode = 1 << 
    // show all embedded methods, not just the ones of
    // invisible (unexported) anonymous fields
    AllMethods
)
 
 
type Note
    
type Note struct {
    Pos, End token. // position range of the comment containing the marker
    UID      string    // uid found with the marker
    Body         // 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
    ImportPath 
    Imports    []string
    Filenames  []
    Notes      map[string][]*
    // but all new code should use Notes instead.
    Bugs []string
    // declarations
    Consts []*
    Types  []*Type
    Vars   []*
    Funcs  []*Func
}
 
Package is the documentation for an entire package.
func New(pkg *.Package, importPath , mode Mode) *
 
New computes the package documentation for the given package AST. New takes
ownership of the AST pkg and may edit or overwrite it.
func (p *Package) Filter(f )
 
Filter eliminates documentation for names that don’t pass through the filter f.
TODO(gri): Recognize “Type.Method” as a name.
type Type struct {
    Doc  string
    Name 
    Decl *ast.
    // associated declarations
    Consts  []*Value // sorted list of constants of (mostly) this type
    Vars    []* // sorted list of variables of (mostly) this type
    Funcs   []*Func  // sorted list of functions returning this type
    Methods []*  // sorted list of methods (including embedded ones) of this type
}
 
Type is the documentation for a type declaration.
type Value
    
type Value struct {
    Doc   string
    Names [] // var or const names in declaration order
    Decl  *ast.
}