Involved Source Files 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.
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 https://go.dev/doc/comment.
To parse the text associated with a doc comment (after removing comment markers),
use a [Parser]:
var p comment.Parser
doc := p.Parse(text)
The result is a [*Doc].
To reformat it as a doc comment, HTML, Markdown, or plain text,
use a [Printer]:
var pr comment.Printer
The [Parser] and [Printer] types are structs whose fields can be
modified to customize the operations.
For details, see the documentation for those types.
Use cases that need additional control over reformatting can
implement their own logic by inspecting the parsed syntax itself.
See the documentation for [Doc], [Block], [Text] for an overview
and links to additional types.html.gomarkdown.goparse.goprint.gostd.gotext.go
A Code is a preformatted code block. 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.
*Code : Block
A DocLink is a link to documentation for a Go package or symbol. 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 // import path // const, func, type, var, or method name // receiver type, without any pointer star, for methods // text of link DefaultURL constructs and returns the documentation URL for l,
using baseURL as a prefix for links to other packages.
The possible forms returned by DefaultURL are:
- baseURL/ImportPath, for a link to another package
- baseURL/ImportPath#Name, for a link to a const, func, type, or var in another package
- baseURL/ImportPath#Recv.Name, for a link to a method in another package
- #Name, for a link to a const, func, type, or var in this package
- #Recv.Name, for a link to a method in this package
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:
"/pkg/" → "/pkg/math/#Sqrt"
"/pkg" → "/pkg/math#Sqrt"
"/" → "/math/#Sqrt"
"" → "/math#Sqrt"
*DocLink : Text
A Heading is a doc comment heading. // the heading text DefaultID returns the default anchor ID for the heading h.
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”.
*Heading : Block
An Italic is a string rendered as italicized text.
Italic : Text
A Link is a link to a specific URL. // is this an automatic (implicit) link of a literal URL? // text of link // target URL of link
*Link : Text
A LinkDef is a single link definition. // the link text // the link URL // whether the comment uses the definition
A List is a numbered or bullet list.
Lists are always non-empty: len(Items) > 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. 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. 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. Items is the list items. 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 [List].ForceBlankBefore. 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 [List].ForceBlankBetween.
*List : Block
A ListItem is a single item in a numbered or bullet list. Content is the list content.
Currently, restrictions in the parser and printer
require every element of Content to be a *Paragraph. // Content of this item. Number is a decimal string in a numbered list
or an empty string in a bullet list. // "1", "2", ...; "" for bullet list
A Paragraph is a paragraph of text. // the heading text
*Paragraph : Block
A Parser is a doc comment parser.
The fields in the struct can be filled in before calling Parse
in order to customize the details of the parsing process. 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. 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. 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. Parse parses the doc comment text and returns the *Doc form.
Comment markers (/* // and */) in the text must have already been removed.
func go/doc.(*Package).Parser() *Parser
A Plain is a string rendered as plain text (not italicized).
Plain : Text
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. DocLinkBaseURL is used when DocLinkURL is nil,
passed to [DocLink.DefaultURL] to construct a DocLink's URL.
See that method's documentation for details. DocLinkURL is a function that computes the URL for the given DocLink.
If DocLinkURL is nil, then link.DefaultURL(p.DocLinkBaseURL) is used. 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. HeadingLevel is the nesting level used for
HTML and Markdown headings.
If HeadingLevel is zero, it defaults to level 3,
meaning to use <h3> and ###. 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". TextPrefix is a prefix to print at the start of every line
when generating text output using the Text method. 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. Comment returns the standard Go formatting of the Doc,
without any comment markers. HTML returns an HTML formatting of the Doc.
See the [Printer] documentation for ways to customize the HTML output. Markdown returns a Markdown formatting of the Doc.
See the [Printer] documentation for ways to customize the Markdown output. Text returns a textual formatting of the Doc.
See the [Printer] documentation for ways to customize the text output.
func go/doc.(*Package).Printer() *Printer
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.
Note that the go/doc package provides a more sophisticated
lookup based on the imports used in the current package.
The pages are generated with Goldsv0.5.5. (GOOS=linux GOARCH=amd64)
Golds is a Go 101 project developed by Tapir Liu.
PR and bug reports are welcome and can be submitted to the issue list.
Please follow @Go100and1 (reachable from the left QR code) to get the latest news of Golds.