import "go/doc"

Overview

Index

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

func Synopsis(s string) string

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

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

type Example

type Filter

type Func

type Mode

type Package

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

    func (p *Package) Filter(f Filter)

type Type

type Value

Package files

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

func Examples

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

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.

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.

Turn each run of multiple \n into </p><p>. Turn each run of indented lines into a <pre> block without indent. Enclose headings with header tags.

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 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.

type Example

type Example struct {
    Name     string // name of the item being exemplified
    Doc      string // example function doc string
    Code     ast.Node
    Comments []*ast.CommentGroup
    Output   string // expected output
}

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
}

Func is the documentation for a func declaration.

type Mode

type Mode int

Mode values control the operation of New.

const (
    // extract documentation for all package-level declarations,
    // not just exported ones
    AllDecls Mode = 1 << iota

    // show all embedded methods, not just the ones of
    // invisible (unexported) anonymous fields
    AllMethods
)

type Package

type Package struct {
    Doc        string
    Name       string
    ImportPath string
    Imports    []string
    Filenames  []string
    Bugs       []string

    // declarations
    Consts []*Value
    Types  []*Type
    Vars   []*Value
    Funcs  []*Func
}

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.

func (*Package) Filter

func (p *Package) Filter(f Filter)

Filter eliminates documentation for names that don't pass through the filter f. TODO: 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
}

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.