From: Russ Cox <rsc@golang.org>
Date: Fri, 6 Jul 2018 01:38:02 +0000 (-0400)
Subject: go/doc: update header rules
X-Git-Tag: go1.11beta2~200
X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=fb72965df06e193bce0b999a0b5cb2a7b817fc7c;p=gostls13.git

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 4228e8cd9c..7c4490e7c3 100644
--- 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.