Package: go/doc

package doc Import Path go/doc (on go.dev) Dependency Relation imports 13 packages, and imported by one package

Involved Source Files comment.go d doc.go Package doc extracts source code documentation from a Go AST. example.go exports.go filter.go reader.go synopsis.go

Code Examples NewFromFiles package main import ( "fmt" "go/ast" "go/doc" "go/parser" "go/token" ) func main() { // src and test are two source files that make up // a package whose documentation will be computed. const src = ` // This is the package comment. package p import "fmt" // This comment is associated with the Greet function. func Greet(who string) { fmt.Printf("Hello, %s!\n", who) } ` const test = ` package p_test // This comment is associated with the ExampleGreet_world example. func ExampleGreet_world() { Greet("world") } ` // Create the AST by parsing src and test. fset := token.NewFileSet() files := []*ast.File{ mustParse(fset, "src.go", src), mustParse(fset, "src_test.go", test), } // Compute package documentation with examples. p, err := doc.NewFromFiles(fset, files, "example.com/p") if err != nil { panic(err) } fmt.Printf("package %s - %s", p.Name, p.Doc) fmt.Printf("func %s - %s", p.Funcs[0].Name, p.Funcs[0].Doc) fmt.Printf(" ⤷ example with suffix %q - %s", p.Funcs[0].Examples[0].Suffix, p.Funcs[0].Examples[0].Doc) } func mustParse(fset *token.FileSet, filename, src string) *ast.File { f, err := parser.ParseFile(fset, filename, src, parser.ParseComments) if err != nil { panic(err) } return f }

Package-Level Functions (total 7)

func Examples(testFiles ...*ast.File) []*Example Examples returns the examples found in testFiles, sorted by Name field. The Order fields record the order in which the examples were encountered. The Suffix field is not populated when Examples is called directly, it is only populated by [NewFromFiles] for examples it finds in _test.go files. Playable Examples must be in a package whose name ends in "_test". An Example is "playable" (the Play field is non-nil) in either of these circumstances: - The example function is self-contained: the function references only identifiers from other packages (or predeclared identifiers, such as "int") and the test file does not include a dot import. - The entire test file is the example: the file contains exactly one example function, zero test, fuzz test, or benchmark function, and at least one top-level function, type, variable, or constant declaration other than the example function.

func IsPredeclared(s string) bool IsPredeclared reports whether s is a predeclared identifier.

func New(pkg *ast.Package, importPath string, mode Mode) *Package New computes the package documentation for the given package AST. New takes ownership of the AST pkg and may edit or overwrite it. To have the [Examples] fields populated, use [NewFromFiles] and include the package's _test.go files.

func NewFromFiles(fset *token.FileSet, files []*ast.File, importPath string, opts ...any) (*Package, error) NewFromFiles computes documentation for a package. The package is specified by a list of *ast.Files and corresponding file set, which must not be nil. NewFromFiles uses all provided files when computing documentation, so it is the caller's responsibility to provide only the files that match the desired build context. "go/build".Context.MatchFile can be used for determining whether a file matches a build context with the desired GOOS and GOARCH values, and other build constraints. The import path of the package is specified by importPath. Examples found in _test.go files are associated with the corresponding type, function, method, or the package, based on their name. If the example has a suffix in its name, it is set in the [Example.Suffix] field. [Examples] with malformed names are skipped. Optionally, a single extra argument of type [Mode] can be provided to control low-level aspects of the documentation extraction behavior. NewFromFiles takes ownership of the AST files and may edit them, unless the PreserveAST Mode bit is on.

func Synopsis(text string) string Synopsis returns a cleaned version of the first sentence in text. Deprecated: New programs should use [Package.Synopsis] instead, which handles links in text properly.

func ToHTML(w io.Writer, text string, words map[string]string) ToHTML converts comment text to formatted HTML. Deprecated: ToHTML cannot identify documentation links in the doc comment, because they depend on knowing what package the text came from, which is not included in this API. Given the *[doc.Package] p where text was found, ToHTML(w, text, nil) can be replaced by: w.Write(p.HTML(text)) which is in turn shorthand for: w.Write(p.Printer().HTML(p.Parser().Parse(text))) If words may be non-nil, the longer replacement is: parser := p.Parser() parser.Words = words w.Write(p.Printer().HTML(parser.Parse(d)))

func ToText(w io.Writer, text string, prefix, codePrefix string, width int) ToText converts comment text to formatted text. Deprecated: ToText cannot identify documentation links in the doc comment, because they depend on knowing what package the text came from, which is not included in this API. Given the *[doc.Package] p where text was found, ToText(w, text, "", "\t", 80) can be replaced by: w.Write(p.Text(text)) In the general case, ToText(w, text, prefix, codePrefix, width) can be replaced by: d := p.Parser().Parse(text) pr := p.Printer() pr.TextPrefix = prefix pr.TextCodePrefix = codePrefix pr.TextWidth = width w.Write(pr.Text(d)) See the documentation for [Package.Text] and [comment.Printer.Text] for more details.

Package-Level Variables (only one)

var IllegalPrefixes []string IllegalPrefixes is a list of lower-case prefixes that identify a comment as not being a doc comment. This helps to avoid misinterpreting the common mistake of a copyright notice immediately before a package statement as being a doc comment.

Package-Level Constants (total 3)

const AllDecls Mode = 1 AllDecls says to extract documentation for all package-level declarations, not just exported ones.

const AllMethods Mode = 2 AllMethods says to show all embedded methods, not just the ones of invisible (unexported) anonymous fields.

const PreserveAST Mode = 4 PreserveAST says to leave the AST unmodified. Originally, pieces of the AST such as function bodies were nil-ed out to save memory in godoc, but not all programs want that behavior.