package comment

Import Path
	go/doc/comment (on go.dev)

Dependency Relation
	imports 8 packages, and imported by 2 packages


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

	    html.go
	    markdown.go
	    parse.go
	    print.go
	    std.go
	    text.go


Package-Level Type Names (total 15)


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

		
			*Code
			*Heading
			*List
			*Paragraph


	
		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 Doc is a parsed Go doc comment.

		
			
				Content is the sequence of content blocks in the comment.

			
				Links is the link definitions in the comment.

		
			func (*Parser).Parse(text string) *Doc
		
			func (*Printer).Comment(d *Doc) []byte
			func (*Printer).HTML(d *Doc) []byte
			func (*Printer).Markdown(d *Doc) []byte
			func (*Printer).Text(d *Doc) []byte


	
		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 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 [Parser.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


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

		
			*DocLink
			 Italic
			*Link
			 Plain




Package-Level Functions (only one)


	
		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.