pkgdoc

Documentation

Overview

Package pkgdoc serves package documentation.

The only API for Go programs is NewServer. The exported data structures are consumed by the templates in _content/lib/godoc/package*.html.

Index

• func NewServer(fsys fs.FS, site *web.Site, forceOld func(*http.Request) bool) (http.Handler, error)
• type Dir
  • func (d *Dir) Name() string
• type DirEntry
  • func (d *DirEntry) Name() string
• type Example
• type Page
  • func (p *Page) Comment(comment string) template.HTML
  • func (*Page) ExampleName(s string) string
  • func (*Page) ExampleSuffix(name string) string
  • func (p *Page) FmtExamples(funcName string) []*Example
  • func (p *Page) ModeQuery() string
  • func (p *Page) Node(node interface{}) template.HTML
  • func (p *Page) NodeTOC(node interface{}) template.HTML
  • func (p *Page) Since(kind, receiver, name string) string
  • func (p *Page) SrcPosLink(n interface{}) template.HTML

Functions

func NewServer

func NewServer(fsys fs.FS, site *web.Site, forceOld func(*http.Request) bool) (http.Handler, error)

NewServer returns an HTTP handler serving package docs for packages loaded from fsys (a tree in GOROOT layout), styled according to site. If forceOld is not nil and returns true for a given request, NewServer will serve docs itself instead of redirecting to pkg.go.dev (forcing the ?m=old behavior).

Types

type Dir

type Dir struct {
	Path     string // directory path
	HasPkg   bool   // true if the directory contains at least one package
	Synopsis string // package documentation, if any
	Dirs     []*Dir // subdirectories
}

func (*Dir) Name

func (d *Dir) Name() string

type DirEntry

type DirEntry struct {
	Depth    int    // >= 0
	Path     string // relative path to directory from listing start
	HasPkg   bool   // true if the directory contains at least one package
	Synopsis string // package documentation, if any
}

DirEntry describes a directory entry. The Depth gives the directory depth relative to the overall list, for use in presenting a hierarchical directory entry.

func (*DirEntry) Name

func (d *DirEntry) Name() string

type Example

type Example struct {
	Page   *Page
	Name   string
	Doc    string
	Code   template.HTML
	Play   string
	Output string
}

type Page

type Page struct {
	OldDocs bool // use ?m=old in doc links

	Dirname string // directory containing the package
	Err     error  // error or nil

	PDoc       *doc.Package   // nil if no package documentation
	Examples   []*doc.Example // nil if no example code
	Bugs       []*doc.Note    // nil if no BUG comments
	IsMain     bool           // true for package main
	IsFiltered bool           // true if results were filtered

	// directory info
	Dirs    []DirEntry // nil if no directory information
	DirFlat bool       // if set, show directory in a flat (non-indented) manner
	// contains filtered or unexported fields
}

func (*Page) Comment

func (p *Page) Comment(comment string) template.HTML

Comment formats the given documentation comment as HTML.

func (*Page) ExampleName

func (*Page) ExampleName(s string) string

ExampleName takes an example function name and returns its display name. For example, "Foo_Bar_quux" becomes "Foo.Bar (Quux)".

func (*Page) ExampleSuffix

func (*Page) ExampleSuffix(name string) string

ExampleSuffix takes an example function name and returns its suffix in parenthesized form. For example, "Foo_Bar_quux" becomes " (Quux)".

func (*Page) FmtExamples

func (p *Page) FmtExamples(funcName string) []*Example

Example renders the examples for the given function name as HTML.

func (*Page) ModeQuery

func (p *Page) ModeQuery() string

ModeQuery returns the "?m=..." query for the current page.

func (*Page) Node

func (p *Page) Node(node interface{}) template.HTML

Node formats the given AST node as HTML. Identifiers in the rendered node are turned into links to their documentation.

func (*Page) NodeTOC

func (p *Page) NodeTOC(node interface{}) template.HTML

NodeTOC formats the given AST node as HTML for inclusion in the table of contents.

func (*Page) Since

func (p *Page) Since(kind, receiver, name string) string

Since reports the Go version that introduced the API feature identified by kind, receiver, name.

func (*Page) SrcPosLink

func (p *Page) SrcPosLink(n interface{}) template.HTML

SrcPosLink returns a link to the specific source code position containing n, which must be either an ast.Node or a *doc.Note.