From ce757e94e028a3c4b490a460b7b8b8266ae38fe4 Mon Sep 17 00:00:00 2001 From: Russ Cox Date: Wed, 1 Jun 2022 22:09:18 -0400 Subject: [PATCH] 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 --- src/go/doc/comment/doc.go | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 src/go/doc/comment/doc.go 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