path: root/devdocs/go/go%2Fdoc%2Findex.html

<h1> Package doc  </h1>     <ul id="short-nav">
<li><code>import "go/doc"</code></li>
<li><a href="#pkg-overview" class="overviewLink">Overview</a></li>
<li><a href="#pkg-index" class="indexLink">Index</a></li>
<li><a href="#pkg-examples" class="examplesLink">Examples</a></li>
<li><a href="#pkg-subdirectories">Subdirectories</a></li>
</ul>     <h2 id="pkg-overview">Overview </h2> <p>Package doc extracts source code documentation from a Go AST. </p>     <h2 id="pkg-index">Index </h2>  <ul id="manual-nav">
<li><a href="#pkg-variables">Variables</a></li>
<li><a href="#IsPredeclared">func IsPredeclared(s string) bool</a></li>
<li><a href="#Synopsis">func Synopsis(text string) string</a></li>
<li><a href="#ToHTML">func ToHTML(w io.Writer, text string, words map[string]string)</a></li>
<li><a href="#ToText">func ToText(w io.Writer, text string, prefix, codePrefix string, width int)</a></li>
<li><a href="#Example">type Example</a></li>
<li> <a href="#Examples">func Examples(testFiles ...*ast.File) []*Example</a>
</li>
<li><a href="#Filter">type Filter</a></li>
<li><a href="#Func">type Func</a></li>
<li><a href="#Mode">type Mode</a></li>
<li><a href="#Note">type Note</a></li>
<li><a href="#Package">type Package</a></li>
<li> <a href="#New">func New(pkg *ast.Package, importPath string, mode Mode) *Package</a>
</li>
<li> <a href="#NewFromFiles">func NewFromFiles(fset *token.FileSet, files []*ast.File, importPath string, opts ...any) (*Package, error)</a>
</li>
<li> <a href="#Package.Filter">func (p *Package) Filter(f Filter)</a>
</li>
<li> <a href="#Package.HTML">func (p *Package) HTML(text string) []byte</a>
</li>
<li> <a href="#Package.Markdown">func (p *Package) Markdown(text string) []byte</a>
</li>
<li> <a href="#Package.Parser">func (p *Package) Parser() *comment.Parser</a>
</li>
<li> <a href="#Package.Printer">func (p *Package) Printer() *comment.Printer</a>
</li>
<li> <a href="#Package.Synopsis">func (p *Package) Synopsis(text string) string</a>
</li>
<li> <a href="#Package.Text">func (p *Package) Text(text string) []byte</a>
</li>
<li><a href="#Type">type Type</a></li>
<li><a href="#Value">type Value</a></li>
</ul> <div id="pkg-examples"> <h3>Examples</h3>  <dl> <dd><a class="exampleLink" href="#example_NewFromFiles">NewFromFiles</a></dd> </dl> </div> <h3>Package files</h3> <p>  <span>comment.go</span> <span>doc.go</span> <span>example.go</span> <span>exports.go</span> <span>filter.go</span> <span>reader.go</span> <span>synopsis.go</span>  </p>   <h2 id="pkg-variables">Variables</h2> <p>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. </p>
<pre data-language="go">var IllegalPrefixes = []string{
    "copyright",
    "all rights",
    "author",
}</pre> <h2 id="IsPredeclared">func <span>IsPredeclared</span>  <span title="Added in Go 1.8">1.8</span> </h2> <pre data-language="go">func IsPredeclared(s string) bool</pre> <p>IsPredeclared reports whether s is a predeclared identifier. </p>
<h2 id="Synopsis">func <span>Synopsis</span>  </h2> <pre data-language="go">func Synopsis(text string) string</pre> <p>Synopsis returns a cleaned version of the first sentence in text. </p>
<p>Deprecated: New programs should use <a href="#Package.Synopsis">Package.Synopsis</a> instead, which handles links in text properly. </p>
<h2 id="ToHTML">func <span>ToHTML</span>  </h2> <pre data-language="go">func ToHTML(w io.Writer, text string, words map[string]string)</pre> <p>ToHTML converts comment text to formatted HTML. </p>
<p>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. </p>
<p>Given the *<a href="#Package">doc.Package</a> p where text was found, ToHTML(w, text, nil) can be replaced by: </p>
<pre data-language="go">w.Write(p.HTML(text))
</pre> <p>which is in turn shorthand for: </p>
<pre data-language="go">w.Write(p.Printer().HTML(p.Parser().Parse(text)))
</pre> <p>If words may be non-nil, the longer replacement is: </p>
<pre data-language="go">parser := p.Parser()
parser.Words = words
w.Write(p.Printer().HTML(parser.Parse(d)))
</pre> <h2 id="ToText">func <span>ToText</span>  </h2> <pre data-language="go">func ToText(w io.Writer, text string, prefix, codePrefix string, width int)</pre> <p>ToText converts comment text to formatted text. </p>
<p>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. </p>
<p>Given the *<a href="#Package">doc.Package</a> p where text was found, ToText(w, text, "", "\t", 80) can be replaced by: </p>
<pre data-language="go">w.Write(p.Text(text))
</pre> <p>In the general case, ToText(w, text, prefix, codePrefix, width) can be replaced by: </p>
<pre data-language="go">d := p.Parser().Parse(text)
pr := p.Printer()
pr.TextPrefix = prefix
pr.TextCodePrefix = codePrefix
pr.TextWidth = width
w.Write(pr.Text(d))
</pre> <p>See the documentation for <a href="#Package.Text">Package.Text</a> and <span>comment.Printer.Text</span> for more details. </p>
<h2 id="Example">type <span>Example</span>  </h2> <p>An Example represents an example function found in a test source file. </p>
<pre data-language="go">type Example struct {
    Name        string // name of the item being exemplified (including optional suffix)
    Suffix      string // example suffix, without leading '_' (only populated by NewFromFiles); added in Go 1.14
    Doc         string // example function doc string
    Code        ast.Node
    Play        *ast.File // a whole program version of the example; added in Go 1.1
    Comments    []*ast.CommentGroup
    Output      string // expected output
    Unordered   bool // Go 1.7
    EmptyOutput bool // expect empty output; added in Go 1.1
    Order       int  // original source code order; added in Go 1.1
}
</pre> <h3 id="Examples">func <span>Examples</span>  </h3> <pre data-language="go">func Examples(testFiles ...*ast.File) []*Example</pre> <p>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 <a href="#NewFromFiles">NewFromFiles</a> for examples it finds in _test.go files. </p>
<p>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: </p>
<ul> <li>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. </li>
<li>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. </li>
</ul> <h2 id="Filter">type <span>Filter</span>  </h2> <pre data-language="go">type Filter func(string) bool</pre> <h2 id="Func">type <span>Func</span>  </h2> <p>Func is the documentation for a func declaration. </p>
<pre data-language="go">type Func struct {
    Doc  string
    Name string
    Decl *ast.FuncDecl

    // methods
    // (for functions, these fields have the respective zero value)
    Recv  string // actual   receiver "T" or "*T" possibly followed by type parameters [P1, ..., Pn]
    Orig  string // original receiver "T" or "*T"
    Level int    // embedding level; 0 means not embedded

    // Examples is a sorted list of examples associated with this
    // function or method. Examples are extracted from _test.go files
    // provided to NewFromFiles.
    Examples []*Example // Go 1.14
}
</pre> <h2 id="Mode">type <span>Mode</span>  </h2> <p>Mode values control the operation of <a href="#New">New</a> and <a href="#NewFromFiles">NewFromFiles</a>. </p>
<pre data-language="go">type Mode int</pre> <pre data-language="go">const (
    // AllDecls says to extract documentation for all package-level
    // declarations, not just exported ones.
    AllDecls Mode = 1 &lt;&lt; iota

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

    // 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.
    PreserveAST
)</pre> <h2 id="Note">type <span>Note</span>  <span title="Added in Go 1.1">1.1</span> </h2> <p>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. </p>
<pre data-language="go">type Note struct {
    Pos, End token.Pos // position range of the comment containing the marker
    UID      string    // uid found with the marker
    Body     string    // note body text
}
</pre> <h2 id="Package">type <span>Package</span>  </h2> <p>Package is the documentation for an entire package. </p>
<pre data-language="go">type Package struct {
    Doc        string
    Name       string
    ImportPath string
    Imports    []string
    Filenames  []string
    Notes      map[string][]*Note // Go 1.1

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

    // declarations
    Consts []*Value
    Types  []*Type
    Vars   []*Value
    Funcs  []*Func

    // Examples is a sorted list of examples associated with
    // the package. Examples are extracted from _test.go files
    // provided to NewFromFiles.
    Examples []*Example // Go 1.14
    // contains filtered or unexported fields
}
</pre> <h3 id="New">func <span>New</span>  </h3> <pre data-language="go">func New(pkg *ast.Package, importPath string, mode Mode) *Package</pre> <p>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 <a href="#Examples">Examples</a> fields populated, use <a href="#NewFromFiles">NewFromFiles</a> and include the package's _test.go files. </p>
<h3 id="NewFromFiles">func <span>NewFromFiles</span>  <span title="Added in Go 1.14">1.14</span> </h3> <pre data-language="go">func NewFromFiles(fset *token.FileSet, files []*ast.File, importPath string, opts ...any) (*Package, error)</pre> <p>NewFromFiles computes documentation for a package. </p>
<p>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. </p>
<p>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. <a href="#Examples">Examples</a> with malformed names are skipped. </p>
<p>Optionally, a single extra argument of type <a href="#Mode">Mode</a> can be provided to control low-level aspects of the documentation extraction behavior. </p>
<p>NewFromFiles takes ownership of the AST files and may edit them, unless the PreserveAST Mode bit is on. </p>   <h4 id="example_NewFromFiles"> <span class="text">Example</span>
</h4> <p>This example illustrates how to use NewFromFiles to compute package documentation with examples. </p> <p>Code:</p> <pre class="code" data-language="go">// 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)

</pre> <p>Output:</p> <pre class="output" data-language="go">package p - This is the package comment.
func Greet - This comment is associated with the Greet function.
 ⤷ example with suffix "world" - This comment is associated with the ExampleGreet_world example.
</pre>   <h3 id="Package.Filter">func (*Package) <span>Filter</span>  </h3> <pre data-language="go">func (p *Package) Filter(f Filter)</pre> <p>Filter eliminates documentation for names that don't pass through the filter f. TODO(gri): Recognize "Type.Method" as a name. </p>
<h3 id="Package.HTML">func (*Package) <span>HTML</span>  <span title="Added in Go 1.19">1.19</span> </h3> <pre data-language="go">func (p *Package) HTML(text string) []byte</pre> <p>HTML returns formatted HTML for the doc comment text. </p>
<p>To customize details of the HTML, use <a href="#Package.Printer">Package.Printer</a> to obtain a <span>comment.Printer</span>, and configure it before calling its HTML method. </p>
<h3 id="Package.Markdown">func (*Package) <span>Markdown</span>  <span title="Added in Go 1.19">1.19</span> </h3> <pre data-language="go">func (p *Package) Markdown(text string) []byte</pre> <p>Markdown returns formatted Markdown for the doc comment text. </p>
<p>To customize details of the Markdown, use <a href="#Package.Printer">Package.Printer</a> to obtain a <span>comment.Printer</span>, and configure it before calling its Markdown method. </p>
<h3 id="Package.Parser">func (*Package) <span>Parser</span>  <span title="Added in Go 1.19">1.19</span> </h3> <pre data-language="go">func (p *Package) Parser() *comment.Parser</pre> <p>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. </p>
<h3 id="Package.Printer">func (*Package) <span>Printer</span>  <span title="Added in Go 1.19">1.19</span> </h3> <pre data-language="go">func (p *Package) Printer() *comment.Printer</pre> <p>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. </p>
<h3 id="Package.Synopsis">func (*Package) <span>Synopsis</span>  <span title="Added in Go 1.19">1.19</span> </h3> <pre data-language="go">func (p *Package) Synopsis(text string) string</pre> <p>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 <a href="#IllegalPrefixes">IllegalPrefixes</a>, the result is the empty string. </p>
<h3 id="Package.Text">func (*Package) <span>Text</span>  <span title="Added in Go 1.19">1.19</span> </h3> <pre data-language="go">func (p *Package) Text(text string) []byte</pre> <p>Text returns formatted text for the doc comment text, wrapped to 80 Unicode code points and using tabs for code block indentation. </p>
<p>To customize details of the formatting, use <a href="#Package.Printer">Package.Printer</a> to obtain a <span>comment.Printer</span>, and configure it before calling its Text method. </p>
<h2 id="Type">type <span>Type</span>  </h2> <p>Type is the documentation for a type declaration. </p>
<pre data-language="go">type Type struct {
    Doc  string
    Name string
    Decl *ast.GenDecl

    // associated declarations
    Consts  []*Value // sorted list of constants of (mostly) this type
    Vars    []*Value // sorted list of variables of (mostly) this type
    Funcs   []*Func  // sorted list of functions returning this type
    Methods []*Func  // sorted list of methods (including embedded ones) of this type

    // Examples is a sorted list of examples associated with
    // this type. Examples are extracted from _test.go files
    // provided to NewFromFiles.
    Examples []*Example // Go 1.14
}
</pre> <h2 id="Value">type <span>Value</span>  </h2> <p>Value is the documentation for a (possibly grouped) var or const declaration. </p>
<pre data-language="go">type Value struct {
    Doc   string
    Names []string // var or const names in declaration order
    Decl  *ast.GenDecl
    // contains filtered or unexported fields
}
</pre> <h2 id="pkg-subdirectories">Subdirectories</h2> <div class="pkg-dir"> <table> <tr> <th class="pkg-name">Name</th> <th class="pkg-synopsis">Synopsis</th> </tr> <tr> <td colspan="2"><a href="../index">..</a></td> </tr> <tr> <td class="pkg-name"> <a href="comment/index">comment</a> </td> <td class="pkg-synopsis"> Package comment implements parsing and reformatting of Go doc comments, (documentation comments), which are comments that immediately precede a top-level declaration of a package, const, func, type, or var. </td> </tr> </table> </div><div class="_attribution">
  <p class="_attribution-p">
    &copy; Google, Inc.<br>Licensed under the Creative Commons Attribution License 3.0.<br>
    <a href="http://golang.org/pkg/go/doc/" class="_attribution-link">http://golang.org/pkg/go/doc/</a>
  </p>
</div>