package godoc

import "golang.org/x/pkgsite/internal/godoc"

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, modInfo *ModuleInfo) ( 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, modInfo *ModuleInfo, nameToVersion map[string]string, bc internal.BuildContext) (_ *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 = 40 * 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.

If you increase this, you may also need to increase MaxFileSize in internal/fetch/limit.go.

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.

Source Files ¶

encode.go encode_ast.gen.go godoc.go render.go

Directories ¶