Documentation
¶
Overview ¶
Package godoc renders Go package documentation to HTML in the pkg.go.dev style.
It is a trimmed, vendored copy of golang.org/x/pkgsite/internal/godoc, reduced to just what llcppg's local documentation server needs: build a Package from already-parsed *ast.File values and render it to HTML. The pkgsite original additionally encodes/decodes ASTs for database storage and extracts module/version metadata; none of that applies to llcppg, which renders a single, freshly generated package straight from disk, so the codec and symbol extraction are omitted. Source linking is kept (see RenderDocLinked): the docserver serves the package source locally, so symbol and "View Source" links can point back at it.
This code (and the HTML templates under dochtml/doc) is BSD-licensed Go Authors code; see the LICENSE file in this directory.
Index ¶
- Constants
- Variables
- func RenderDoc(ctx context.Context, fset *token.FileSet, d *doc.Package) (_ *dochtml.Parts, err error)
- func RenderDocLinked(ctx context.Context, fset *token.FileSet, d *doc.Package, opts LinkOptions) (_ *dochtml.Parts, err error)
- type File
- type LinkOptions
- type ModuleInfo
- type Package
Constants ¶
const (
// Exported for tests.
DocTooLargeReplacement = `<p>Documentation is too large to display.</p>`
)
Variables ¶
var ErrTooLarge = dochtml.ErrTooLarge
ErrTooLarge is returned (wrapped) when rendered documentation exceeds the configured size limit.
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.
It is a variable for testing.
Functions ¶
func RenderDoc ¶
func RenderDoc(ctx context.Context, fset *token.FileSet, d *doc.Package) (_ *dochtml.Parts, err error)
RenderDoc renders an already-built doc.Package to HTML with source linking disabled. See RenderDocLinked for the variant that links symbols to their source. fset must be the file set the package was parsed with.
func RenderDocLinked ¶
func RenderDocLinked(ctx context.Context, fset *token.FileSet, d *doc.Package, opts LinkOptions) (_ *dochtml.Parts, err error)
RenderDocLinked renders an already-built doc.Package to HTML, linking symbols and files to their source via opts. It is useful for callers (like llcppg's docserver) that construct the doc.Package themselves with go/doc and want the pkg.go.dev-style HTML rendering, without handing the raw ASTs to this package. fset must be the file set the package was parsed with.
Types ¶
type LinkOptions ¶
type LinkOptions struct {
// SourceLinkFunc returns the URL to link a declaration's source to, given
// the declaration's AST node. Returning "" leaves the symbol unlinked.
SourceLinkFunc func(ast.Node) string
// FileLinkFunc returns the URL to link a .go file name to. Returning ""
// leaves the file unlinked.
FileLinkFunc func(file string) string
}
LinkOptions configures how RenderDocLinked turns declarations and files into links back to their source. A nil func (or one returning the empty string) disables the corresponding link, matching RenderDoc's behaviour.
type ModuleInfo ¶
type ModuleInfo = dochtml.ModuleInfo
ModuleInfo re-exports dochtml.ModuleInfo for callers that still construct it. llcppg does not populate it, but keeping the alias mirrors the pkgsite API.
type Package ¶
A Package contains package-level information needed to render Go documentation.
func NewPackage ¶
NewPackage returns a new Package with the given file set. If allDecls is true, unexported declarations are included (doc.AllDecls).
func (*Package) AddFile ¶
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) DocPackage ¶
DocPackage computes and returns a doc.Package for the given import path.
It is a trimmed version of the pkgsite original: llcppg always renders a single, locally parsed package, so the module/version and standard-library ("builtin") special cases of pkgsite's DocPackage are not needed.
doc.NewFromFiles consumes the comment associations of the ASTs it is given, so DocPackage (and therefore Render) must be called at most once for a given set of files; a caller that already holds a *doc.Package should use the package-level RenderDoc instead.
func (*Package) Render ¶
Render renders the documentation for the package under importPath.
It is a trimmed version of the pkgsite original: there is no module versioning or "since version" information, because llcppg serves a single freshly generated package from disk rather than a versioned module from a database. Source links are left disabled (RenderDoc's defaults); a caller that can serve the package source should use RenderDocLinked instead. Rendering destroys p's AST; do not call any methods of p after it returns.
Source Files