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 AnchorSpan
• type Assembler
  • func (a *Assembler) Assemble(bpkg *gosrc.Package) (*Package, error)
• type Code
• type CodeBuilder
  • func (cb *CodeBuilder) Build(src []byte, regions []gosrc.Region) *Code
• type CommentSpan
• type DeclFormatter
• type ErrorSpan
• type Function
• type LinkSpan
• type Linker
• type Package
• type Span
• type TextSpan
• 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 AnchorSpan

type AnchorSpan struct {
	Text []byte
	ID   string
}

AnchorSpan renders as an addressable anchor point.

type Assembler

type Assembler struct {
	Linker Linker
	// 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 Code

type Code struct {
	Spans []Span
}

Code is a code block comprised of multiple text nodes.

type CodeBuilder

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

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

func (*CodeBuilder) Build

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

Build builds a 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 CommentSpan

type CommentSpan struct {
	Text []byte
}

CommentSpan renders as slightly muted text.

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 ErrorSpan

type ErrorSpan struct {
	Msg string
	Err error
}

ErrorSpan is a special span that represents a failure operation.

This renders in HTML in a visible way to avoid failing silently.

type Function

type Function struct {
	Name      string
	Doc       *comment.Doc
	Decl      *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 LinkSpan

type LinkSpan struct {
	Text []byte
	Dest string
}

LinkSpan renders as a link with a specific destination.

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
	Synopsis   string

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

Package holds documentation for a single Go package.

type Span

type Span interface {
	// contains filtered or unexported methods
}

Span is a part of a code block.

type TextSpan

type TextSpan struct {
	Text []byte
}

TextSpan is a span rendered as-is.

type Type

type Type struct {
	Name string
	Doc  *comment.Doc
	Decl *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  *Code
}

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