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

<h1> Package comment  </h1>     <ul id="short-nav">
<li><code>import "go/doc/comment"</code></li>
<li><a href="#pkg-overview" class="overviewLink">Overview</a></li>
<li><a href="#pkg-index" class="indexLink">Index</a></li>
</ul>     <h2 id="pkg-overview">Overview </h2> <p>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. </p>
<p>Go doc comment syntax is a simplified subset of Markdown that supports links, headings, paragraphs, lists (without nesting), and preformatted text blocks. The details of the syntax are documented at <a href="https://go.dev/doc/comment">https://go.dev/doc/comment</a>. </p>
<p>To parse the text associated with a doc comment (after removing comment markers), use a <a href="#Parser">Parser</a>: </p>
<pre data-language="go">var p comment.Parser
doc := p.Parse(text)
</pre> <p>The result is a <a href="#Doc">*Doc</a>. To reformat it as a doc comment, HTML, Markdown, or plain text, use a <a href="#Printer">Printer</a>: </p>
<pre data-language="go">var pr comment.Printer
os.Stdout.Write(pr.Text(doc))
</pre> <p>The <a href="#Parser">Parser</a> and <a href="#Printer">Printer</a> types are structs whose fields can be modified to customize the operations. For details, see the documentation for those types. </p>
<p>Use cases that need additional control over reformatting can implement their own logic by inspecting the parsed syntax itself. See the documentation for <a href="#Doc">Doc</a>, <a href="#Block">Block</a>, <a href="#Text">Text</a> for an overview and links to additional types. </p>     <h2 id="pkg-index">Index </h2>  <ul id="manual-nav">
<li><a href="#DefaultLookupPackage">func DefaultLookupPackage(name string) (importPath string, ok bool)</a></li>
<li><a href="#Block">type Block</a></li>
<li><a href="#Code">type Code</a></li>
<li><a href="#Doc">type Doc</a></li>
<li><a href="#DocLink">type DocLink</a></li>
<li> <a href="#DocLink.DefaultURL">func (l *DocLink) DefaultURL(baseURL string) string</a>
</li>
<li><a href="#Heading">type Heading</a></li>
<li> <a href="#Heading.DefaultID">func (h *Heading) DefaultID() string</a>
</li>
<li><a href="#Italic">type Italic</a></li>
<li><a href="#Link">type Link</a></li>
<li><a href="#LinkDef">type LinkDef</a></li>
<li><a href="#List">type List</a></li>
<li> <a href="#List.BlankBefore">func (l *List) BlankBefore() bool</a>
</li>
<li> <a href="#List.BlankBetween">func (l *List) BlankBetween() bool</a>
</li>
<li><a href="#ListItem">type ListItem</a></li>
<li><a href="#Paragraph">type Paragraph</a></li>
<li><a href="#Parser">type Parser</a></li>
<li> <a href="#Parser.Parse">func (p *Parser) Parse(text string) *Doc</a>
</li>
<li><a href="#Plain">type Plain</a></li>
<li><a href="#Printer">type Printer</a></li>
<li> <a href="#Printer.Comment">func (p *Printer) Comment(d *Doc) []byte</a>
</li>
<li> <a href="#Printer.HTML">func (p *Printer) HTML(d *Doc) []byte</a>
</li>
<li> <a href="#Printer.Markdown">func (p *Printer) Markdown(d *Doc) []byte</a>
</li>
<li> <a href="#Printer.Text">func (p *Printer) Text(d *Doc) []byte</a>
</li>
<li><a href="#Text">type Text</a></li>
</ul> <h3>Package files</h3> <p>  <span>doc.go</span> <span>html.go</span> <span>markdown.go</span> <span>parse.go</span> <span>print.go</span> <span>std.go</span> <span>text.go</span>  </p>   <h2 id="DefaultLookupPackage">func <span>DefaultLookupPackage</span>  <span title="Added in Go 1.19">1.19</span> </h2> <pre data-language="go">func DefaultLookupPackage(name string) (importPath string, ok bool)</pre> <p>DefaultLookupPackage is the default package lookup function, used when [Parser.LookupPackage] is nil. It recognizes names of the packages from the standard library with single-element import paths, such as math, which would otherwise be impossible to name. </p>
<p>Note that the go/doc package provides a more sophisticated lookup based on the imports used in the current package. </p>
<h2 id="Block">type <span>Block</span>  <span title="Added in Go 1.19">1.19</span> </h2> <p>A Block is block-level content in a doc comment, one of <a href="#Code">*Code</a>, <a href="#Heading">*Heading</a>, <a href="#List">*List</a>, or <a href="#Paragraph">*Paragraph</a>. </p>
<pre data-language="go">type Block interface {
    // contains filtered or unexported methods
}</pre> <h2 id="Code">type <span>Code</span>  <span title="Added in Go 1.19">1.19</span> </h2> <p>A Code is a preformatted code block. </p>
<pre data-language="go">type Code struct {
    // Text is the preformatted text, ending with a newline character.
    // It may be multiple lines, each of which ends with a newline character.
    // It is never empty, nor does it start or end with a blank line.
    Text string
}
</pre> <h2 id="Doc">type <span>Doc</span>  <span title="Added in Go 1.19">1.19</span> </h2> <p>A Doc is a parsed Go doc comment. </p>
<pre data-language="go">type Doc struct {
    // Content is the sequence of content blocks in the comment.
    Content []Block

    // Links is the link definitions in the comment.
    Links []*LinkDef
}
</pre> <h2 id="DocLink">type <span>DocLink</span>  <span title="Added in Go 1.19">1.19</span> </h2> <p>A DocLink is a link to documentation for a Go package or symbol. </p>
<pre data-language="go">type DocLink struct {
    Text []Text // text of link

    // ImportPath, Recv, and Name identify the Go package or symbol
    // that is the link target. The potential combinations of
    // non-empty fields are:
    //  - ImportPath: a link to another package
    //  - ImportPath, Name: a link to a const, func, type, or var in another package
    //  - ImportPath, Recv, Name: a link to a method in another package
    //  - Name: a link to a const, func, type, or var in this package
    //  - Recv, Name: a link to a method in this package
    ImportPath string // import path
    Recv       string // receiver type, without any pointer star, for methods
    Name       string // const, func, type, var, or method name
}
</pre> <h3 id="DocLink.DefaultURL">func (*DocLink) <span>DefaultURL</span>  <span title="Added in Go 1.19">1.19</span> </h3> <pre data-language="go">func (l *DocLink) DefaultURL(baseURL string) string</pre> <p>DefaultURL constructs and returns the documentation URL for l, using baseURL as a prefix for links to other packages. </p>
<p>The possible forms returned by DefaultURL are: </p>
<ul> <li>baseURL/ImportPath, for a link to another package </li>
<li>baseURL/ImportPath#Name, for a link to a const, func, type, or var in another package </li>
<li>baseURL/ImportPath#Recv.Name, for a link to a method in another package </li>
<li>#Name, for a link to a const, func, type, or var in this package </li>
<li>#Recv.Name, for a link to a method in this package </li>
</ul> <p>If baseURL ends in a trailing slash, then DefaultURL inserts a slash between ImportPath and # in the anchored forms. For example, here are some baseURL values and URLs they can generate: </p>
<pre data-language="go">"/pkg/" → "/pkg/math/#Sqrt"
"/pkg"  → "/pkg/math#Sqrt"
"/"     → "/math/#Sqrt"
""      → "/math#Sqrt"
</pre> <h2 id="Heading">type <span>Heading</span>  <span title="Added in Go 1.19">1.19</span> </h2> <p>A Heading is a doc comment heading. </p>
<pre data-language="go">type Heading struct {
    Text []Text // the heading text
}
</pre> <h3 id="Heading.DefaultID">func (*Heading) <span>DefaultID</span>  <span title="Added in Go 1.19">1.19</span> </h3> <pre data-language="go">func (h *Heading) DefaultID() string</pre> <p>DefaultID returns the default anchor ID for the heading h. </p>
<p>The default anchor ID is constructed by converting every rune that is not alphanumeric ASCII to an underscore and then adding the prefix “hdr-”. For example, if the heading text is “Go Doc Comments”, the default ID is “hdr-Go_Doc_Comments”. </p>
<h2 id="Italic">type <span>Italic</span>  <span title="Added in Go 1.19">1.19</span> </h2> <p>An Italic is a string rendered as italicized text. </p>
<pre data-language="go">type Italic string</pre> <h2 id="Link">type <span>Link</span>  <span title="Added in Go 1.19">1.19</span> </h2> <p>A Link is a link to a specific URL. </p>
<pre data-language="go">type Link struct {
    Auto bool   // is this an automatic (implicit) link of a literal URL?
    Text []Text // text of link
    URL  string // target URL of link
}
</pre> <h2 id="LinkDef">type <span>LinkDef</span>  <span title="Added in Go 1.19">1.19</span> </h2> <p>A LinkDef is a single link definition. </p>
<pre data-language="go">type LinkDef struct {
    Text string // the link text
    URL  string // the link URL
    Used bool   // whether the comment uses the definition
}
</pre> <h2 id="List">type <span>List</span>  <span title="Added in Go 1.19">1.19</span> </h2> <p>A List is a numbered or bullet list. Lists are always non-empty: len(Items) &gt; 0. In a numbered list, every Items[i].Number is a non-empty string. In a bullet list, every Items[i].Number is an empty string. </p>
<pre data-language="go">type List struct {
    // Items is the list items.
    Items []*ListItem

    // ForceBlankBefore indicates that the list must be
    // preceded by a blank line when reformatting the comment,
    // overriding the usual conditions. See the BlankBefore method.
    //
    // The comment parser sets ForceBlankBefore for any list
    // that is preceded by a blank line, to make sure
    // the blank line is preserved when printing.
    ForceBlankBefore bool

    // ForceBlankBetween indicates that list items must be
    // separated by blank lines when reformatting the comment,
    // overriding the usual conditions. See the BlankBetween method.
    //
    // The comment parser sets ForceBlankBetween for any list
    // that has a blank line between any two of its items, to make sure
    // the blank lines are preserved when printing.
    ForceBlankBetween bool
}
</pre> <h3 id="List.BlankBefore">func (*List) <span>BlankBefore</span>  <span title="Added in Go 1.19">1.19</span> </h3> <pre data-language="go">func (l *List) BlankBefore() bool</pre> <p>BlankBefore reports whether a reformatting of the comment should include a blank line before the list. The default rule is the same as for [BlankBetween]: if the list item content contains any blank lines (meaning at least one item has multiple paragraphs) then the list itself must be preceded by a blank line. A preceding blank line can be forced by setting <a href="#List">List</a>.ForceBlankBefore. </p>
<h3 id="List.BlankBetween">func (*List) <span>BlankBetween</span>  <span title="Added in Go 1.19">1.19</span> </h3> <pre data-language="go">func (l *List) BlankBetween() bool</pre> <p>BlankBetween reports whether a reformatting of the comment should include a blank line between each pair of list items. The default rule is that if the list item content contains any blank lines (meaning at least one item has multiple paragraphs) then list items must themselves be separated by blank lines. Blank line separators can be forced by setting <a href="#List">List</a>.ForceBlankBetween. </p>
<h2 id="ListItem">type <span>ListItem</span>  <span title="Added in Go 1.19">1.19</span> </h2> <p>A ListItem is a single item in a numbered or bullet list. </p>
<pre data-language="go">type ListItem struct {
    // Number is a decimal string in a numbered list
    // or an empty string in a bullet list.
    Number string // "1", "2", ...; "" for bullet list

    // Content is the list content.
    // Currently, restrictions in the parser and printer
    // require every element of Content to be a *Paragraph.
    Content []Block // Content of this item.
}
</pre> <h2 id="Paragraph">type <span>Paragraph</span>  <span title="Added in Go 1.19">1.19</span> </h2> <p>A Paragraph is a paragraph of text. </p>
<pre data-language="go">type Paragraph struct {
    Text []Text
}
</pre> <h2 id="Parser">type <span>Parser</span>  <span title="Added in Go 1.19">1.19</span> </h2> <p>A Parser is a doc comment parser. The fields in the struct can be filled in before calling <a href="#Parser.Parse">Parser.Parse</a> in order to customize the details of the parsing process. </p>
<pre data-language="go">type Parser struct {
    // Words is a map of Go identifier words that
    // should be italicized and potentially linked.
    // If Words[w] is the empty string, then the word w
    // is only italicized. Otherwise it is linked, using
    // Words[w] as the link target.
    // Words corresponds to the [go/doc.ToHTML] words parameter.
    Words map[string]string

    // LookupPackage resolves a package name to an import path.
    //
    // If LookupPackage(name) returns ok == true, then [name]
    // (or [name.Sym] or [name.Sym.Method])
    // is considered a documentation link to importPath's package docs.
    // It is valid to return "", true, in which case name is considered
    // to refer to the current package.
    //
    // If LookupPackage(name) returns ok == false,
    // then [name] (or [name.Sym] or [name.Sym.Method])
    // will not be considered a documentation link,
    // except in the case where name is the full (but single-element) import path
    // of a package in the standard library, such as in [math] or [io.Reader].
    // LookupPackage is still called for such names,
    // in order to permit references to imports of other packages
    // with the same package names.
    //
    // Setting LookupPackage to nil is equivalent to setting it to
    // a function that always returns "", false.
    LookupPackage func(name string) (importPath string, ok bool)

    // LookupSym reports whether a symbol name or method name
    // exists in the current package.
    //
    // If LookupSym("", "Name") returns true, then [Name]
    // is considered a documentation link for a const, func, type, or var.
    //
    // Similarly, if LookupSym("Recv", "Name") returns true,
    // then [Recv.Name] is considered a documentation link for
    // type Recv's method Name.
    //
    // Setting LookupSym to nil is equivalent to setting it to a function
    // that always returns false.
    LookupSym func(recv, name string) (ok bool)
}
</pre> <h3 id="Parser.Parse">func (*Parser) <span>Parse</span>  <span title="Added in Go 1.19">1.19</span> </h3> <pre data-language="go">func (p *Parser) Parse(text string) *Doc</pre> <p>Parse parses the doc comment text and returns the *<a href="#Doc">Doc</a> form. Comment markers (/* // and */) in the text must have already been removed. </p>
<h2 id="Plain">type <span>Plain</span>  <span title="Added in Go 1.19">1.19</span> </h2> <p>A Plain is a string rendered as plain text (not italicized). </p>
<pre data-language="go">type Plain string</pre> <h2 id="Printer">type <span>Printer</span>  <span title="Added in Go 1.19">1.19</span> </h2> <p>A Printer is a doc comment printer. The fields in the struct can be filled in before calling any of the printing methods in order to customize the details of the printing process. </p>
<pre data-language="go">type Printer struct {
    // HeadingLevel is the nesting level used for
    // HTML and Markdown headings.
    // If HeadingLevel is zero, it defaults to level 3,
    // meaning to use &lt;h3&gt; and ###.
    HeadingLevel int

    // HeadingID is a function that computes the heading ID
    // (anchor tag) to use for the heading h when generating
    // HTML and Markdown. If HeadingID returns an empty string,
    // then the heading ID is omitted.
    // If HeadingID is nil, h.DefaultID is used.
    HeadingID func(h *Heading) string

    // DocLinkURL is a function that computes the URL for the given DocLink.
    // If DocLinkURL is nil, then link.DefaultURL(p.DocLinkBaseURL) is used.
    DocLinkURL func(link *DocLink) string

    // DocLinkBaseURL is used when DocLinkURL is nil,
    // passed to [DocLink.DefaultURL] to construct a DocLink's URL.
    // See that method's documentation for details.
    DocLinkBaseURL string

    // TextPrefix is a prefix to print at the start of every line
    // when generating text output using the Text method.
    TextPrefix string

    // TextCodePrefix is the prefix to print at the start of each
    // preformatted (code block) line when generating text output,
    // instead of (not in addition to) TextPrefix.
    // If TextCodePrefix is the empty string, it defaults to TextPrefix+"\t".
    TextCodePrefix string

    // TextWidth is the maximum width text line to generate,
    // measured in Unicode code points,
    // excluding TextPrefix and the newline character.
    // If TextWidth is zero, it defaults to 80 minus the number of code points in TextPrefix.
    // If TextWidth is negative, there is no limit.
    TextWidth int
}
</pre> <h3 id="Printer.Comment">func (*Printer) <span>Comment</span>  <span title="Added in Go 1.19">1.19</span> </h3> <pre data-language="go">func (p *Printer) Comment(d *Doc) []byte</pre> <p>Comment returns the standard Go formatting of the <a href="#Doc">Doc</a>, without any comment markers. </p>
<h3 id="Printer.HTML">func (*Printer) <span>HTML</span>  <span title="Added in Go 1.19">1.19</span> </h3> <pre data-language="go">func (p *Printer) HTML(d *Doc) []byte</pre> <p>HTML returns an HTML formatting of the <a href="#Doc">Doc</a>. See the <a href="#Printer">Printer</a> documentation for ways to customize the HTML output. </p>
<h3 id="Printer.Markdown">func (*Printer) <span>Markdown</span>  <span title="Added in Go 1.19">1.19</span> </h3> <pre data-language="go">func (p *Printer) Markdown(d *Doc) []byte</pre> <p>Markdown returns a Markdown formatting of the Doc. See the <a href="#Printer">Printer</a> documentation for ways to customize the Markdown output. </p>
<h3 id="Printer.Text">func (*Printer) <span>Text</span>  <span title="Added in Go 1.19">1.19</span> </h3> <pre data-language="go">func (p *Printer) Text(d *Doc) []byte</pre> <p>Text returns a textual formatting of the <a href="#Doc">Doc</a>. See the <a href="#Printer">Printer</a> documentation for ways to customize the text output. </p>
<h2 id="Text">type <span>Text</span>  <span title="Added in Go 1.19">1.19</span> </h2> <p>A Text is text-level content in a doc comment, one of <a href="#Plain">Plain</a>, <a href="#Italic">Italic</a>, <a href="#Link">*Link</a>, or <a href="#DocLink">*DocLink</a>. </p>
<pre data-language="go">type Text interface {
    // contains filtered or unexported methods
}</pre><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/comment/" class="_attribution-link">http://golang.org/pkg/go/doc/comment/</a>
  </p>
</div>