From: Russ Cox Date: Thu, 2 Jun 2022 02:09:18 +0000 (-0400) Subject: go/doc/comment: add doc comment X-Git-Tag: go1.19beta1~51 X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=ce757e94e028a3c4b490a460b7b8b8266ae38fe4;p=gostls13.git go/doc/comment: add doc comment A CL in the website repo will add go.dev/doc/comment. One of the final steps for #51082. Change-Id: I419b4f6dbb424a8a93a8d09db30f7321af9ae976 Reviewed-on: https://go-review.googlesource.com/c/go/+/410358 TryBot-Result: Gopher Robot Run-TryBot: Russ Cox Reviewed-by: Ian Lance Taylor --- diff --git a/src/go/doc/comment/doc.go b/src/go/doc/comment/doc.go new file mode 100644 index 0000000000..45a476aa9a --- /dev/null +++ b/src/go/doc/comment/doc.go @@ -0,0 +1,36 @@ +// Copyright 2022 The Go Authors. All rights reserved. +// Use of this source code is governed by a BSD-style +// license that can be found in the LICENSE file. + +/* +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. +*/ +package comment