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

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

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

ensonic opened this issue Apr 29, 2019 · 4 comments

Comments

@ensonic
Copy link

@ensonic 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
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: 94f9bf20042b5bf00ac9fb8d4b36cb4da04a7913
@ensonic
Copy link
Author

@ensonic ensonic commented Apr 29, 2019

@dmitshur
Copy link
Member

@dmitshur dmitshur commented Apr 29, 2019

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

@dmitshur dmitshur commented Apr 29, 2019

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
3 participants
You can’t perform that action at this time.