package doc

Import Path
	go/doc (on go.dev)

Dependency Relation
	imports 13 packages, and imported by one package


Involved Source Files

	    comment.go
	
		Package doc extracts source code documentation from a Go AST.

	    example.go
	    exports.go
	    filter.go
	    reader.go
	    synopsis.go


Code Examples

	
		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 Type Names (total 12, in which 8 are exported)


	/* sort exporteds by:  |  */
	
		An Example represents an example function found in a test source file.

		
			Code ast.Node
			Comments []*ast.CommentGroup
			
				// example function doc string

			
				// expect empty output

			
				// name of the item being exemplified (including optional suffix)

			
				// original source code order

			
				// expected output

			
				// a whole program version of the example

			
				// example suffix, without leading '_' (only populated by NewFromFiles)

			Unordered bool
		
			func Examples(testFiles ...*ast.File) []*Example
		
			


	

		
			func (*Package).Filter(f Filter)
			


	
		Func is the documentation for a func declaration.

		
			Decl *ast.FuncDecl
			Doc string
			
				Examples is a sorted list of examples associated with this
				function or method. Examples are extracted from _test.go files
				provided to NewFromFiles.

			
				// embedding level; 0 means not embedded

			Name string
			
				// original receiver "T" or "*T"

			
				methods
				(for functions, these fields have the respective zero value)
				// actual   receiver "T" or "*T" possibly followed by type parameters [P1, ..., Pn]

		
			
		
			


	
		Mode values control the operation of [New] and [NewFromFiles].

		
			func New(pkg *ast.Package, importPath string, mode Mode) *Package
		
			const AllDecls
			const AllMethods
			const PreserveAST


	
		A Note represents a marked comment starting with "MARKER(uid): note body".
		Any note with a marker of 2 or more upper case [A-Z] letters and a uid of
		at least one character is recognized. The ":" following the uid is optional.
		Notes are collected in the Package.Notes map indexed by the notes marker.

		
			
				// note body text

			
				// position range of the comment containing the marker

			
				// position range of the comment containing the marker

			
				// uid found with the marker

		
			


	
		Package is the documentation for an entire package.

		
			
				Deprecated: For backward compatibility Bugs is still populated,
				but all new code should use Notes instead.

			
				declarations

			Doc string
			
				Examples is a sorted list of examples associated with
				the package. Examples are extracted from _test.go files
				provided to NewFromFiles.

			Filenames []string
			Funcs []*Func
			ImportPath string
			Imports []string
			Name string
			Notes map[string][]*Note
			Types []*Type
			Vars []*Value
			
		
			
				Filter eliminates documentation for names that don't pass through the filter f.
				TODO(gri): Recognize "Type.Method" as a name.

			
				HTML returns formatted HTML for the doc comment text.
				
				To customize details of the HTML, use [Package.Printer]
				to obtain a [comment.Printer], and configure it
				before calling its HTML method.

			
				Markdown returns formatted Markdown for the doc comment text.
				
				To customize details of the Markdown, use [Package.Printer]
				to obtain a [comment.Printer], and configure it
				before calling its Markdown method.

			
				Parser returns a doc comment parser configured
				for parsing doc comments from package p.
				Each call returns a new parser, so that the caller may
				customize it before use.

			
				Printer returns a doc comment printer configured
				for printing doc comments from package p.
				Each call returns a new printer, so that the caller may
				customize it before use.

			
				Synopsis returns a cleaned version of the first sentence in text.
				That sentence ends after the first period followed by space and not
				preceded by exactly one uppercase letter, or at the first paragraph break.
				The result string has no \n, \r, or \t characters and uses only single
				spaces between words. If text starts with any of the [IllegalPrefixes],
				the result is the empty string.

			
				Text returns formatted text for the doc comment text,
				wrapped to 80 Unicode code points and using tabs for
				code block indentation.
				
				To customize details of the formatting, use [Package.Printer]
				to obtain a [comment.Printer], and configure it
				before calling its Text method.

			
		
			func New(pkg *ast.Package, importPath string, mode Mode) *Package
			func NewFromFiles(fset *token.FileSet, files []*ast.File, importPath string, opts ...any) (*Package, error)
		
			


	
		Type is the documentation for a type declaration.

		
			
				associated declarations
				// sorted list of constants of (mostly) this type

			Decl *ast.GenDecl
			Doc string
			
				Examples is a sorted list of examples associated with
				this type. Examples are extracted from _test.go files
				provided to NewFromFiles.

			
				// sorted list of functions returning this type

			
				// sorted list of methods (including embedded ones) of this type

			Name string
			
				// sorted list of variables of (mostly) this type

		
			
		
			


	
		Value is the documentation for a (possibly grouped) var or const declaration.

		
			Decl *ast.GenDecl
			Doc string
			
				// var or const names in declaration order

			
		
			
		
			


	


Package-Level Functions (total 51, in which 7 are exported)


	
		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.


	
		IsPredeclared reports whether s is a predeclared identifier.


	
		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.


	
		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.


	
		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.


	
		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)))


	
		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 (total 9, in which 1 is exported)


	
		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, all are exported)


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


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


	
		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.