doc.go

     1  // Copyright 2022 The Go Authors. All rights reserved.
     2  // Use of this source code is governed by a BSD-style
     3  // license that can be found in the LICENSE file.
     4  
     5  /*
     6  Package comment implements parsing and reformatting of Go doc comments,
     7  (documentation comments), which are comments that immediately precede
     8  a top-level declaration of a package, const, func, type, or var.
     9  
    10  Go doc comment syntax is a simplified subset of Markdown that supports
    11  links, headings, paragraphs, lists (without nesting), and preformatted text blocks.
    12  The details of the syntax are documented at https://go.dev/doc/comment.
    13  
    14  To parse the text associated with a doc comment (after removing comment markers),
    15  use a [Parser]:
    16  
    17  	var p comment.Parser
    18  	doc := p.Parse(text)
    19  
    20  The result is a [*Doc].
    21  To reformat it as a doc comment, HTML, Markdown, or plain text,
    22  use a [Printer]:
    23  
    24  	var pr comment.Printer
    25  	os.Stdout.Write(pr.Text(doc))
    26  
    27  The [Parser] and [Printer] types are structs whose fields can be
    28  modified to customize the operations.
    29  For details, see the documentation for those types.
    30  
    31  Use cases that need additional control over reformatting can
    32  implement their own logic by inspecting the parsed syntax itself.
    33  See the documentation for [Doc], [Block], [Text] for an overview
    34  and links to additional types.
    35  */
    36  package comment
    37
View as plain text