godoc

Package godoc provides the means of converting parsed Go source information into a documentation subset of it.

package godoc

import "go.abhg.dev/doc2go/internal/godoc"

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

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
	Logger *log.Logger // optional

	// 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 Example

type Example struct {
	// Parent is the name of the entity this example is for.
	//
	// If Parent is empty, this is a package example.
	Parent ExampleParent

	// Suffix is the description of this example
	// following the entity association.
	//
	// This may be empty.
	Suffix string

	// Doc is the documentation for this example.
	Doc *comment.Doc

	// Code is the lexically analyzed code for this example,
	// ready to be syntax-highlighted.
	Code *highlight.Code

	// Output is the output expected from this example, if any.
	Output string
}

Example is a testable example found in a _test.go file. Each example is associated with either a package, a function, a type, or a method.

type ExampleParent

type ExampleParent struct {
	Recv string
	Name string
}

ExampleParent is a parent of a code example.

Valid configurations for it are:

  • package: Recv and Name are empty
  • function or type: Recv is empty, Name is set
  • method: Recv and Name are set

func (ExampleParent) String

func (p ExampleParent) String() string

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 '*'
	Examples   []*Example
	Deprecated bool
}

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
	Examples  []*Example

	// All examples in the package and its children.
	AllExamples []*Example
}

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

	Examples   []*Example
	Deprecated bool
}

Type is a single top-level type.

type Value

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

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