godoc

Documentation

Overview

Package godoc provides the means of converting parsed Go source information into a documentation subset of it. This information is neessary to render documentation for a package.

Index

• func OneLineNodeDepth(fset *token.FileSet, node ast.Node, depth int) string
• type Assembler
  • func (a *Assembler) Assemble(bpkg *gosrc.Package) (*Package, error)
• type CodeBuilder
  • func (cb *CodeBuilder) Build(src []byte, regions []gosrc.Region) *highlight.Code
• type DeclFormatter
• type Function
• type Linker
• type Package
• type Type
• type Value

Functions

func OneLineNodeDepth

func OneLineNodeDepth(fset *token.FileSet, node ast.Node, depth int) string

OneLineNodeDepth returns a one-line summary of the given input node. The depth specifies the current depth when traversing the AST and the function will stop traversing once depth reaches maxSynopsisNodeDepth.

Types

type Assembler

type Assembler struct {
	Linker Linker

	// Lexer used to highlight code blocks.
	Lexer highlight.Lexer
	// contains filtered or unexported fields
}

Assembler assembles a Package from a go/doc.Package.

func (*Assembler) Assemble

func (a *Assembler) Assemble(bpkg *gosrc.Package) (*Package, error)

Assemble runs the assembler on the given doc.Package.

type CodeBuilder

type CodeBuilder struct {
	DocLinkURL func(*comment.DocLink) string
	Lexer      highlight.Lexer
}

CodeBuilder builds highlight.Code blocks, using the provided linker to resolve links to entities.

func (*CodeBuilder) Build

func (cb *CodeBuilder) Build(src []byte, regions []gosrc.Region) *highlight.Code

Build builds a highlight.Code containing the provided source, annotated with the provided regions.

Panics if regions are out of bounds in src, or an unknown region is encountered.

type DeclFormatter

type DeclFormatter interface {
	FormatDecl(ast.Decl) (src []byte, regions []gosrc.Region, err error)
}

DeclFormatter formats an AST declaration for rendering in documentation.

type Function

type Function struct {
	Name      string
	Doc       *comment.Doc
	Decl      *highlight.Code
	ShortDecl string
	Recv      string // only set for methods
	RecvType  string // name of the receiver type without '*'
}

Function is a top-level function or method.

type Linker

type Linker interface {
	DocLinkURL(fromPkg string, link *comment.DocLink) string
}

Linker generates links to the documentation for a specific package or entity.

type Package

type Package struct {
	Name string
	Doc  *comment.Doc // package-level documentation

	// Empty if the package isn't a binary.
	BinName string

	ImportPath string
	Import     *highlight.Code // code form of import path
	Synopsis   string

	Constants []*Value
	Variables []*Value
	Types     []*Type
	Functions []*Function
}

Package holds documentation for a single Go package.

type Type

type Type struct {
	Name string
	Doc  *comment.Doc
	Decl *highlight.Code

	// Constants, variables, functions, and methods
	// associated with this type.
	Constants, Variables []*Value
	Functions, Methods   []*Function
}

Type is a single top-level type.

type Value

type Value struct {
	Names []string
	Doc   *comment.Doc
	Decl  *highlight.Code
}

Value is a top-level constant or variable or a group fo them declared in a package.