go/doc: lines ending with parenthesis cannot be headings

[billyjacobson]

What did you do?
Add a package doc like:

// ...
// Create a snapshot from a source table (snapshots alpha)
//
// cbt createsnapshot <cluster> <snapshot> <table> [ttl=<d>]
// ...

What did you expect to see?
The string "Create a snapshot..." should be a title since it is delimited by blank lines, starts with and uppercase letter and does not end with an invalid punctuation.

What did you see instead?
It shows up as a regular text paragraph.
Can be seen here: https://godoc.org/google.golang.org/cloud/bigtable/cmd/cbt#hdr-Block_until_all_the_completed_writes_have_been_replicated_to_all_the_clusters

cc: @dmitshur

[dmitshur]

Thank you for reporting.

The implementation contains a rule that a heading "must end in a letter or digit", which is preventing a heading that ends with ')' to become a title. See:

go/src/go/doc/comment.go

Lines 226 to 230 in 7987238

	// it must end in a letter or digit:
	r, _ = utf8.DecodeLastRuneInString(line)
	if !unicode.IsLetter(r) && !unicode.IsDigit(r) {
	return ""
	}

That rule isn't mentioned in the doc.ToHTML documentation. We'll need to decide whether to update the documentation or to fix the implementation.

[vdobler]

We needed some way to distinguish a headline from a simple sentence.
A very early implementation used two preceding blank line to signal
a heading but this was considered to be markup and some heuristic was
chosen to distinguish a heading. This heuristic produces several false
negatives, like this issue or that you cannot have a headline in a script
without uppercase characters. In Englisch (european languages in general)
you can reword a heading to match the rules.

Proper documentation fixes only half of the problem. We could allow
the headline to end in a ")" if preceded by a matching "(". And document this.
But this process becomes endless: You still cannot have "Reaching 99.5%"
as a heading but "Reaching (99.5%)" would be rendered as a heading.

While I dislike markup in code comments I think the rules for a good heading
heuristic are even worse than non-invasive markup like two preceding blank
lines.

[rsc]

See #48305.