go/doc: lines with double-quotes cannot be headings

[ensonic]

What did you do?

Add a package doc like:

// ...
// The behaviour can be customized by annotations on the CRDs.
//
// Annotation "annotation-name"
//
//   example.com/annotation-name: <bool>
//
// If true, lorem ipsum ...
//

What did you expect to see?

The string Annotation "annotation-name" should be a title since it is delimited by blank lines, starts with and uppercase letter and does not end with punctuation.

What did you see instead?

It shows up as a regular text paragraph. I've also tested simply putting the work Annotation there to exclude the quotes.

[ensonic]

Actual example here:
https://godoc.org/github.com/googlecloudrobotics/core/src/go/cmd/cr-syncer

[dmitshur]

See https://godoc.org/go/doc#ToHTML for the rules of what makes a heading:

a span that consists of a single line, is followed by another paragraph span, begins with a capital letter, and contains no punctuation other than parentheses and commas is formatted as a heading.

[dmitshur]

Specifically, that line isn't recognized as a heading because it contains the " character, which is neither parenthesis nor comma.

Here's the check in code:

go/src/go/doc/comment.go

Lines 232 to 235 in 76659e4

	// exclude lines with illegal characters. we allow "(),"
	if strings.ContainsAny(line, ";:!?+*/=[]{}_^°&§~%#@<\">\\") {
	return ""
	}

[ensonic]

Like I said, I also just tried 'Annotation' in the above example to exclude that it is due to the '"', but it was still not recognized as a heading.

[jpap]

Is there a technical reason why we couldn't use quotes in titles? I hit this today, and was forced to reword the title, but that did not quite capture the original meaning. Would love to see quotes (double, and/or single) be included in the title allow-list!

[rsc]

See #48305.