Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

go/doc: lines ending with parenthesis cannot be headings #34377

billyjacobson opened this issue Sep 18, 2019 · 2 comments

go/doc: lines ending with parenthesis cannot be headings #34377

billyjacobson opened this issue Sep 18, 2019 · 2 comments


Copy link

@billyjacobson billyjacobson commented Sep 18, 2019

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:

cc: @dmitshur

@dmitshur dmitshur added this to the Go1.14 milestone Sep 18, 2019
Copy link

@dmitshur dmitshur commented Sep 18, 2019

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:


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.

Copy link

@vdobler vdobler commented Sep 25, 2019

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

@rsc rsc modified the milestones: Go1.14, Backlog Oct 9, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
4 participants