comment

Documentation

Overview

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
os.Stdout.Write(pr.Text(doc))

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.

Index

• func DefaultLookupPackage(name string) (importPath string, ok bool)
• type Block
• type Code
• type Doc
• type DocLink
  • func (l *DocLink) DefaultURL(baseURL string) string
• type Heading
  • func (h *Heading) DefaultID() string
• type Italic
• type Link
• type LinkDef
• type List
  • func (l *List) BlankBefore() bool
  • func (l *List) BlankBetween() bool
• type ListItem
• type Paragraph
• type Parser
  • func (p *Parser) Parse(text string) *Doc
• type Plain
• type Printer
  • func (p *Printer) Comment(d *Doc) []byte
  • func (p *Printer) HTML(d *Doc) []byte
  • func (p *Printer) Markdown(d *Doc) []byte
  • func (p *Printer) Text(d *Doc) []byte
• type Text

Functions

func DefaultLookupPackage

func DefaultLookupPackage(name string) (importPath string, ok bool)

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.

Types

type Block

type Block interface {
	// contains filtered or unexported methods
}

A Block is block-level content in a doc comment, one of *Code, *Heading, *List, or *Paragraph.

type Code

type Code struct {
	Text string
}

A Code is a preformatted code block.

type Doc

type Doc struct {
	Content []Block

	Links []*LinkDef
}

A Doc is a parsed Go doc comment.

type DocLink

type DocLink struct {
	Text []Text

	ImportPath string
	Recv       string
	Name       string
}

A DocLink is a link to documentation for a Go package or symbol.

func (*DocLink) DefaultURL

func (l *DocLink) DefaultURL(baseURL string) string

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"

type Heading

type Heading struct {
	Text []Text
}

A Heading is a doc comment heading.

func (*Heading) DefaultID

func (h *Heading) DefaultID() string

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”.

type Italic

type Italic string

An Italic is a string rendered as italicized text.

type Link

type Link struct {
	Auto bool
	Text []Text
	URL  string
}

A Link is a link to a specific URL.

type LinkDef

type LinkDef struct {
	Text string
	URL  string
	Used bool
}

A LinkDef is a single link definition.

type List

type List struct {
	Items []*ListItem

	ForceBlankBefore bool

	ForceBlankBetween bool
}

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.

func (*List) BlankBefore

func (l *List) BlankBefore() bool

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.

func (*List) BlankBetween

func (l *List) BlankBetween() bool

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.

type ListItem

type ListItem struct {
	Number string

	Content []Block
}

A ListItem is a single item in a numbered or bullet list.

type Paragraph

type Paragraph struct {
	Text []Text
}

A Paragraph is a paragraph of text.

type Parser

type Parser struct {
	Words map[string]string

	LookupPackage func(name string) (importPath string, ok bool)

	LookupSym func(recv, name string) (ok bool)
}

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.

func (*Parser) Parse

func (p *Parser) Parse(text string) *Doc

Parse parses the doc comment text and returns the *Doc form. Comment markers (/* // and */) in the text must have already been removed.

type Plain

type Plain string

A Plain is a string rendered as plain text (not italicized).

type Printer

type Printer struct {
	HeadingLevel int

	HeadingID func(h *Heading) string

	DocLinkURL func(link *DocLink) string

	DocLinkBaseURL string

	TextPrefix string

	TextCodePrefix string

	TextWidth int
}

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.

func (*Printer) Comment

func (p *Printer) Comment(d *Doc) []byte

Comment returns the standard Go formatting of the Doc, without any comment markers.

func (*Printer) HTML

func (p *Printer) HTML(d *Doc) []byte

HTML returns an HTML formatting of the Doc. See the Printer documentation for ways to customize the HTML output.

func (*Printer) Markdown

func (p *Printer) Markdown(d *Doc) []byte

Markdown returns a Markdown formatting of the Doc. See the Printer documentation for ways to customize the Markdown output.

func (*Printer) Text

func (p *Printer) Text(d *Doc) []byte

Text returns a textual formatting of the Doc. See the Printer documentation for ways to customize the text output.

type Text

type Text interface {
	// contains filtered or unexported methods
}

A Text is text-level content in a doc comment, one of Plain, Italic, *Link, or *DocLink.