Go: x/pkgsite/internal/fetch/dochtml/internal/render: first paragraph should not be considered as a potential section heading

[hajimehoshi]

What version of Go are you using (go version)?

n/a

Does this issue reproduce with the latest release?

n/a

What operating system and processor architecture are you using (go env)?

n/a

What did you do?

Open https://pkg.go.dev/github.com/hajimehoshi/[email protected]#hdr-DrawRectShaderOptions_represents_options_for_DrawRectShader

What did you expect to see?

The text "DrawRectShaderOptions represents options for DrawRectShader" should be a normal text.

What did you see instead?

The text seems a header. Actually this is represented with a <h3> element.

[julieqiu]

Thanks for the feedback! If anyone is interested in working on this, we'd love to accept a contribution for this fix.

[trongbq]

@julieqiu I'd love to help, may I work on this one?

[julieqiu]

@trongbq, please do!

[trongbq]

@hajimehoshi pkgsite's render recognizes that comment is a heading because the comment follows heading style. More details explanation bellow.

In the source code, the comment is written like this

// DrawRectShaderOptions represents options for DrawRectShader
//
// This API is experimental.

If you look at the first line, you can see that it doesn't have period mark at the end.
pkgsite's render uses following regex to identify heading, which return true for that line.

// Regexp for headings.
headingHead = `^[\p{Lu}]`                                  // any uppercase letter
headingBody = `([^,.;:!?+*/=()\[\]{}_^°&§~%#@<">\\]|'s )*` // any non-illegal character
headingTail = `([\p{L}\p{Nd}]|'s)?$`                       // any letter or digit

Is is okay for you that I will send a PR to add period mark at the end for comments like this? It will make comment style in your code be consistent.

@julieqiu I wonder should we keep existing check for header in comment. Do you think this is an issue need to be fixed in pkgsite? Personally, I think we can just keep pkgsite's render as it is.

P/s: I looked in godoc, that comment above is displayed normally without any headers. I didn't look deeper into the godoc source but I think that godoc doesn't have heading style.

[julieqiu]

Is is okay for you that I will send a PR to add period mark at the end for comments like this? It will make comment style in your code be consistent.

SGTM, thanks!

/cc @dmitshur for input on this issue

[hajimehoshi]

Is is okay for you that I will send a PR to add period mark at the end for comments like this?

Thanks, that'd be helpful!

[dmitshur]

@trongbq Thank you for investigating this.

This godoc behavior is called a "section heading" and it is currently best documented in the second paragraph of "go/doc".ToHTML:

Each span of unindented non-blank lines is converted into a single paragraph. There is one exception to the rule: 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.

It is also mentioned in the .../dochtml/interal/render package documentation, see here.

The go/doc implementation actually has additional conditions that need to be met for a line to be considered a heading: it must be immediately preceded by a blank line, and a non-heading paragraph before that.

The render package in pkgsite doesn't seem to check what came before the heading, so may consider the first line in the doc string as a heading. Given that comments for exported identifiers are expected to begin with the name of the identifier itself and be a complete sentence, not supporting headings in the first line (as godoc does) seems like the better behavior.

[trongbq]

@dmitshur thank you for such a clear explanation.

not supporting headings in the first line (as godoc does) seems like the better behavior.

I see, let's me try to implement this behavior in render package.

[gopherbot]

Change https://golang.org/cl/258398 mentions this issue: render: first paragraph should not be considered as a potential section heading.