Namespace: go.std.go.doc.comment

v1.0

Contents

• Summary
• Index
• Constants
• Variables
• Functions, Macros, and Special Forms
• Types

Summary

Provides a low-level interface to the go/doc/comment package.

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

• *Code
• *Doc
• *DocLink
• *Heading
• *Italic
• *Link
• *LinkDef
• *List
• *ListItem
• *Paragraph
• *Parser
• *Plain
• *Printer
• Block
• Code
• DefaultLookupPackage
• Doc
• DocLink
• Heading
• Italic
• Link
• LinkDef
• List
• ListItem
• Paragraph
• Parser
• Plain
• Printer
• Text
• arrayOfBlock
• arrayOfCode
• arrayOfDoc
• arrayOfDocLink
• arrayOfHeading
• arrayOfItalic
• arrayOfLink
• arrayOfLinkDef
• arrayOfList
• arrayOfListItem
• arrayOfParagraph
• arrayOfParser
• arrayOfPlain
• arrayOfPrinter
• arrayOfText

Legend

Constant Variable Function Macro Special form Type GoVar Receiver/Method

Constants

Constants are variables with :const true in their metadata. Joker currently does not recognize them as special; as such, it allows redefining them or their values.

(None.)

Variables

(None.)

Functions, Macros, and Special Forms

• DefaultLookupPackage

  Function v1.0

  (DefaultLookupPackage name)
  

  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.
  
  Go input arguments: (name string)
  
  Go returns: (importPath string, ok bool)
  
  Joker input arguments: [^String name]
  
  Joker returns: [^String importPath, ^Boolean ok]

Types

• *Code

  Concrete Type v1.0

  A Code is a preformatted code block.
  

• *Doc

  Concrete Type v1.0

  A Doc is a parsed Go doc comment.
  

• *DocLink

  Concrete Type v1.0

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

• DefaultURL

  Receiver for *DocLink v1.0

  ([baseURL])
  

  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"
  

• *Heading

  Concrete Type v1.0

  A Heading is a doc comment heading.
  

• DefaultID

  Receiver for *Heading v1.0

  ([])
  

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

• *Italic

  Concrete Type v1.0

  An Italic is a string rendered as italicized text.
  

• *Link

  Concrete Type v1.0

  A Link is a link to a specific URL.
  

• *LinkDef

  Concrete Type v1.0

  A LinkDef is a single link definition.
  

• *List

  Concrete Type v1.0

  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.
  

• BlankBefore

  Receiver for *List v1.0

  ([])
  

  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

  Receiver for *List v1.0

  ([])
  

  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.
  

• *ListItem

  Concrete Type v1.0

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

• *Paragraph

  Concrete Type v1.0

  A Paragraph is a paragraph of text.
  

• *Parser

  Concrete Type v1.0

  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.
  

• Parse

  Receiver for *Parser v1.0

  ([text])
  

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

• *Plain

  Concrete Type v1.0

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

• *Printer

  Concrete Type v1.0

  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.
  

• Comment

  Receiver for *Printer v1.0

  ([d])
  

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

• HTML

  Receiver for *Printer v1.0

  ([d])
  

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

• Markdown

  Receiver for *Printer v1.0

  ([d])
  

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

• Text

  Receiver for *Printer v1.0

  ([d])
  

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

• Block

  Abstract Type v1.0

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

• Code

  Concrete Type v1.0

  A Code is a preformatted code block.
  

• Doc

  Concrete Type v1.0

  A Doc is a parsed Go doc comment.
  

• DocLink

  Concrete Type v1.0

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

• Heading

  Concrete Type v1.0

  A Heading is a doc comment heading.
  

• Italic

  Concrete Type v1.0

  An Italic is a string rendered as italicized text.
  

• Link

  Concrete Type v1.0

  A Link is a link to a specific URL.
  

• LinkDef

  Concrete Type v1.0

  A LinkDef is a single link definition.
  

• List

  Concrete Type v1.0

  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.
  

• ListItem

  Concrete Type v1.0

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

• Paragraph

  Concrete Type v1.0

  A Paragraph is a paragraph of text.
  

• Parser

  Concrete Type v1.0

  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.
  

• Plain

  Concrete Type v1.0

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

• Printer

  Concrete Type v1.0

  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.
  

• Text

  Abstract Type v1.0

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

• arrayOfBlock

  Concrete Type v1.0

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

• arrayOfCode

  Concrete Type v1.0

  A Code is a preformatted code block.
  

• arrayOfDoc

  Concrete Type v1.0

  A Doc is a parsed Go doc comment.
  

• arrayOfDocLink

  Concrete Type v1.0

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

• arrayOfHeading

  Concrete Type v1.0

  A Heading is a doc comment heading.
  

• arrayOfItalic

  Concrete Type v1.0

  An Italic is a string rendered as italicized text.
  

• arrayOfLink

  Concrete Type v1.0

  A Link is a link to a specific URL.
  

• arrayOfLinkDef

  Concrete Type v1.0

  A LinkDef is a single link definition.
  

• arrayOfList

  Concrete Type v1.0

  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.
  

• arrayOfListItem

  Concrete Type v1.0

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

• arrayOfParagraph

  Concrete Type v1.0

  A Paragraph is a paragraph of text.
  

• arrayOfParser

  Concrete Type v1.0

  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.
  

• arrayOfPlain

  Concrete Type v1.0

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

• arrayOfPrinter

  Concrete Type v1.0

  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.
  

• arrayOfText

  Concrete Type v1.0

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