doc

Documentation

Overview

The doc package extracts source code documentation from a Go AST.

Index

• func CommentText(comment *ast.CommentGroup) string
• func ToHTML(w io.Writer, s []byte)
• type FuncDoc
• type PackageDoc
  • func NewFileDoc(file *ast.File) *PackageDoc
  • func NewPackageDoc(pkg *ast.Package, importpath string) *PackageDoc
  • func (p *PackageDoc) Filter(names []string)
• 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)

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 <pre> without indent.

TODO(rsc): I'd like to pass in an array of variable names []string and then italicize those strings when they appear as words.

Types

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(names []string)

Filter eliminates information from d that is not about one of the given names. TODO: Recognize "Type.Method" as a name. TODO(r): maybe precompile the regexps.

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