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

Open
billyjacobson opened this issue Sep 18, 2019 · 2 comments

Comments

@billyjacobson
Copy link

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: 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 dmitshur added this to the Go1.14 milestone Sep 18, 2019
@dmitshur

This comment has been minimized.

Copy link
Member

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:

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

This comment has been minimized.

Copy link
Contributor

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
lines.

@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
Projects
None yet
4 participants
You can’t perform that action at this time.