godoc

Documentation

Overview

Package godoc is for rendering Go documentation.

Index

• Constants
• Variables
• func RenderFromUnit(ctx context.Context, u *internal.Unit, bc internal.BuildContext) (_ *dochtml.Parts, err error)
• type File
• type ModuleInfo
• type Package
  • func DecodePackage(data []byte) (_ *Package, err error)
  • func NewPackage(fset *token.FileSet, modPaths map[string]bool) *Package
  • func (p *Package) AddFile(f *ast.File, removeNodes bool)
  • func (p *Package) DocInfo(ctx context.Context, innerPath string, sourceInfo *source.Info, ...) (synopsis string, imports []string, api []*internal.Symbol, err error)
  • func (p *Package) DocPackage(innerPath string, modInfo *ModuleInfo) (_ *doc.Package, err error)
  • func (p *Package) Encode(ctx context.Context) (_ []byte, err error)
  • func (p *Package) Render(ctx context.Context, innerPath string, sourceInfo *source.Info, ...) (_ *dochtml.Parts, err error)

Constants

const (

	// Exported for tests.
	DocTooLargeReplacement = `<p>Documentation is too large to display.</p>`
)

Variables

var ErrInvalidEncodingType = fmt.Errorf("want initial bytes to be %q but they aren't", fastEncodingType)

ErrInvalidEncodingType is returned when the data to DecodePackage has an invalid encoding type.

var ErrTooLarge = dochtml.ErrTooLarge

var MaxDocumentationHTML = 20 * megabyte

MaxDocumentationHTML is a limit on the rendered documentation HTML size.

The current limit of is based on the largest packages that pkg.go.dev has encountered. See https://golang.org/issue/40576.

It is a variable for testing.

var TypesToGenerate = []any{&encPackage{}}

Used by the gen program to generate encodings for unexported types.

Functions

func RenderFromUnit

func RenderFromUnit(ctx context.Context, u *internal.Unit,
	bc internal.BuildContext) (_ *dochtml.Parts, err error)

RenderFromUnit is a convenience function that first decodes the source in the unit, which must exist, and then calls Render.

Types

type File

type File struct {
	Name string // full file pathname relative to zip content directory
	AST  *ast.File
}

A File contains everything needed about a source file to render documentation.

type ModuleInfo

type ModuleInfo = dochtml.ModuleInfo

type Package

type Package struct {
	Fset *token.FileSet
	// contains filtered or unexported fields
}

A Package contains package-level information needed to render Go documentation.

func DecodePackage

func DecodePackage(data []byte) (_ *Package, err error)

DecodePackage decodes a byte slice encoded with Package.Encode into a Package.

func NewPackage

func NewPackage(fset *token.FileSet, modPaths map[string]bool) *Package

NewPackage returns a new Package with the given fset and set of module package paths.

func (*Package) AddFile

func (p *Package) AddFile(f *ast.File, removeNodes bool)

AddFile adds a file to the Package. After it returns, the contents of the ast.File are unsuitable for anything other than the methods of this package.

func (*Package) DocInfo

func (p *Package) DocInfo(ctx context.Context, innerPath string, sourceInfo *source.Info, modInfo *ModuleInfo) (
	synopsis string, imports []string, api []*internal.Symbol, err error)

DocInfo returns information extracted from the package's documentation. This destroys p's AST; do not call any methods of p after it returns.

func (*Package) DocPackage

func (p *Package) DocPackage(innerPath string, modInfo *ModuleInfo) (_ *doc.Package, err error)

DocPackage computes and returns a doc.Package.

func (*Package) Encode

func (p *Package) Encode(ctx context.Context) (_ []byte, err error)

Encode encodes a Package into a byte slice. During its operation, Encode modifies the AST, but it restores it to a state suitable for rendering before it returns.

func (*Package) Render

func (p *Package) Render(ctx context.Context, innerPath string,
	sourceInfo *source.Info, modInfo *ModuleInfo, nameToVersion map[string]string,
	bc internal.BuildContext) (_ *dochtml.Parts, err error)

Render renders the documentation for the package. Rendering destroys p's AST; do not call any methods of p after it returns.