go/doc: Synopsis can return a sentence spanning multiple paragraphs and code blocks #31947
Let "paragraph" mean a block of text separated from other text by a blank line (i.e.,
fmt.Println(doc.Synopsis(`This is a sentence that starts in the first paragraph and it keeps going in the second paragraph and ends in the third paragraph. This is the second sentence.`)) // Output: This is a sentence that starts in the first paragraph and it keeps going in the second paragraph and ends in the third paragraph.
(Playground link: https://play.golang.org/p/hSAetYyxkwa)
Perhaps we should consider changing the logic such that a sentence is not allowed to span multiple paragraphs.
From what I've observed, that is rarely used intentionally, but can happen unintentionally. For example, the current version of the
Edit: Another one is
Edit 2: Another one is
The text was updated successfully, but these errors were encountered:
Sounds good. To make progress on this issue, we should run that experiment and confirm the results are favorable. We should be able to include a corpus with a number of third-party packages in the experiment, in addition to the standard library packages.
I ran an experiment on the standard library and some modules that were recently published (by using the module index). The results seem favorable, and there are quite a few cases where the synopsis extends well beyond the first paragraph.
First, there is one diff in the standard library:
It's a good change. It helps with a case in the
There are more diffs in the golang.org/x modules:
These changes seem favorable too. Most happen because the first sentence is missing a period. A few happen because there is a period but it is not recognized due to a quote character, or being mistaken for an acronym.
The benchcmp change is questionable, but its documentation doesn't follow the suggested style of starting a package comment with "Package [name] ..."; the deprecated paragraph needs to be moved below.
In third-party packages, the vast majority of instances have a zero diff (9505 .go files out of 1070 unique modules). There are instances where the diff is non-zero (91 .go files out of 1061 unique modules). The changes overall look favorable. In many cases, they help reduce an accidentally very long synopsis to one that is much shorter and more readable. In the remaining cases, it turns a poor synopsis into a slightly shorter but also poor synopsis. You can see the raw data here.
Based on this data, I think it's reasonable to move this issue to NeedsFix state. @griesemer Do you agree?