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

Jump to bottom

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

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

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

billyjacobson opened this issue Sep 18, 2019 · 3 comments
Labels
NeedsDecision Feedback is required from experts, contributors, and/or the community before a change can be made. Thinking
Milestone
Backlog

Comments

@billyjacobson
Copy link

billyjacobson commented Sep 18, 2019 •
edited

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 the NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. label Sep 18, 2019
@dmitshur dmitshur added this to the Go1.14 milestone Sep 18, 2019
@dmitshur
Copy link
Contributor

dmitshur commented Sep 18, 2019 •
edited

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.

@dmitshur dmitshur added NeedsDecision Feedback is required from experts, contributors, and/or the community before a change can be made. Thinking and removed NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. labels Sep 18, 2019
@vdobler
Copy link
Contributor

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

@rsc rsc modified the milestones: Go1.14, Backlog Oct 9, 2019
@rsc
Copy link
Contributor

rsc commented Sep 10, 2021

See #48305.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
NeedsDecision Feedback is required from experts, contributors, and/or the community before a change can be made. Thinking
Projects
None yet
Milestone
Backlog
Development

No branches or pull requests
4 participants
@rsc @vdobler @dmitshur @billyjacobson