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 with double-quotes cannot be headings #31739

Open
ensonic opened this issue Apr 29, 2019 · 6 comments
Open

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

ensonic opened this issue Apr 29, 2019 · 6 comments
Labels
NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one.
Milestone
Unreleased

Comments

@ensonic
Copy link

ensonic commented Apr 29, 2019

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.
@gopherbot gopherbot added this to the Unreleased milestone Apr 29, 2019
cloud-robotics-github-robot pushed a commit to googlecloudrobotics/core that referenced this issue Apr 29, 2019
@ensonic
Improve the formatting of the crsyncer docs.
515a0b0 
This will render the annotations specs as code which acts as a visual
divider. Unfortunately the heuristic for detecting sub-titles does not seem
to work here (filed a go bug golang/go#31739).

Change-Id: I6cd0d01170c3047c03f1a31b260fa0f98e53d296
GitOrigin-RevId: 94f9bf2
@ensonic
Copy link
Author

ensonic commented Apr 29, 2019

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

@dmitshur
Copy link
Contributor

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

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 ""
}

@dmitshur dmitshur changed the title x/tools/cmd/godoc: titles don't work go/doc: lines with double-quotes cannot be headings Apr 29, 2019
@ensonic
Copy link
Author

ensonic commented May 3, 2019

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
Copy link
Contributor

jpap commented Jul 18, 2021

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
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
NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one.
Projects
None yet
Milestone
Unreleased
Development

No branches or pull requests
5 participants
@rsc @jpap @ensonic @dmitshur @gopherbot