go/doc: update header rules

Go documentation can have header lines, which are single-line paragraphs
with leading and trailing letters and almost no punctuation.
Before this CL, the only allowed punctuation was ' followed by s.

After this CL, parentheses and commas are also allowed,
to pick up a pair of previously unrecognized headings in the
go command documentation:

	Gofmt (reformat) package sources
	Modules, module versions, and more

Change-Id: I6d59c40a1269f01cef62a3fb17b909571c2f2adb
Reviewed-on: https://go-review.googlesource.com/122407
Run-TryBot: Russ Cox <rsc@golang.org>
Reviewed-by: Andrew Bonventre <andybons@golang.org>

diff --git a/src/go/doc/comment.go b/src/go/doc/comment.go
index 4228e8cd9c5573000984b0d38c581561fa88ea62..7c4490e7c3a03d2633ea2b3af16ead66e788a78f 100644 (file)
--- a/src/go/doc/comment.go
+++ b/src/go/doc/comment.go
@@ -231,8 +231,8 @@ func heading(line string) string {
                return ""
        }
 
-       // exclude lines with illegal characters
-       if strings.ContainsAny(line, ",.;:!?+*/=()[]{}_^°&§~%#@<\">\\") {
+       // exclude lines with illegal characters. we allow "(),"
+       if strings.ContainsAny(line, ".;:!?+*/=[]{}_^°&§~%#@<\">\\") {
                return ""
        }
 
@@ -281,7 +281,7 @@ func anchorID(line string) string {
 // a single paragraph. There is one exception to the rule: a span that
 // consists of a single line, is followed by another paragraph span,
 // begins with a capital letter, and contains no punctuation
-// is formatted as a heading.
+// other than parentheses and commas is formatted as a heading.
 //
 // A span of indented lines is converted into a <pre> block,
 // with the common indent prefix removed.