doc

Documentation

Overview

Package doc extracts source code documentation from a Go AST.

Index

• func CommentText(comment *ast.CommentGroup) string
• func ToHTML(w io.Writer, s []byte, words map[string]string)
• type Filter
• type FuncDoc
• type PackageDoc
  • func NewFileDoc(file *ast.File) *PackageDoc
  • func NewPackageDoc(pkg *ast.Package, importpath string) *PackageDoc
  • func (p *PackageDoc) Filter(f Filter)
• type TypeDoc
• type ValueDoc
• Bugs

Functions

func CommentText

func CommentText(comment *ast.CommentGroup) string

CommentText returns the text of comment, with the comment markers - //, /*, and */ - removed.

func ToHTML

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

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

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.

Types

type Filter

type Filter func(string) bool

type FuncDoc

type FuncDoc struct {
	Doc  string
	Recv ast.Expr // TODO(rsc): Would like string here
	Name string
	Decl *ast.FuncDecl
}

FuncDoc is the documentation for a func declaration, either a top-level function or a method function.

type PackageDoc

type PackageDoc struct {
	PackageName string
	ImportPath  string
	Filenames   []string
	Doc         string
	Consts      []*ValueDoc
	Types       []*TypeDoc
	Vars        []*ValueDoc
	Funcs       []*FuncDoc
	Bugs        []string
}

PackageDoc is the documentation for an entire package.

func NewFileDoc

func NewFileDoc(file *ast.File) *PackageDoc

func NewPackageDoc

func NewPackageDoc(pkg *ast.Package, importpath string) *PackageDoc

func (*PackageDoc) Filter

func (p *PackageDoc) Filter(f Filter)

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

type TypeDoc

type TypeDoc struct {
	Doc       string
	Type      *ast.TypeSpec
	Consts    []*ValueDoc
	Vars      []*ValueDoc
	Factories []*FuncDoc
	Methods   []*FuncDoc
	Decl      *ast.GenDecl
	// contains filtered or unexported fields
}

TypeDoc is the documentation for a declared type. Consts and Vars are sorted lists of constants and variables of (mostly) that type. Factories is a sorted list of factory functions that return that type. Methods is a sorted list of method functions on that type.

type ValueDoc

type ValueDoc struct {
	Doc  string
	Decl *ast.GenDecl
	// contains filtered or unexported fields
}

ValueDoc is the documentation for a group of declared values, either vars or consts.

Notes

Bugs