What did you do?
Wrote a package doc comment such as "Package foo frobulates things e.g. red frobs and green frobs. It can also unfrobulate things." and used (directly, or indirectly e.g. examining output on the pkg website) go/doc.Synopsis to return the first sentence of the text.
What did you expect to see?
go/doc.Synopsis formats this text as "Package foo frobulates things e.g. red frobs and green frobs."
What did you see instead?
go/doc.Synopsis formats this text as "Package foo frobulates things e.g."
The problem is likely not one we want to solve by changing the behaviour of go/doc.Synopsis (see discussion on #59189).
The problem is that the documentation refers to "first sentence", it does so with a specific meaning as defined by go/doc.Synopsis, and not with the meaning a reader would have in mind, of natural language in whatever language the comment is written in. This can be surprising.
The solution should be for the main points of reference for learning how to document Go code to explain this better at the first instance of the phrase "first sentence", perhaps by inserting a footnote.
In https://go.dev/blog/godoc:
When writing package comments of any size, keep in mind that their first sentence[1] will appear in godoc’s package list.
In https://tip.golang.org/doc/comment:
As can be seen in this example, Go doc comments use complete sentences. For a package comment, that means the first sentence[1] begins with “Package”.
With a footnote such as:
1: The meaning of "first sentence" here is specified exactly by [go.doc/Synopsis].
What did you do?
Wrote a package doc comment such as "Package foo frobulates things e.g. red frobs and green frobs. It can also unfrobulate things." and used (directly, or indirectly e.g. examining output on the pkg website) go/doc.Synopsis to return the first sentence of the text.
What did you expect to see?
go/doc.Synopsis formats this text as "Package foo frobulates things e.g. red frobs and green frobs."
What did you see instead?
go/doc.Synopsis formats this text as "Package foo frobulates things e.g."
The problem is likely not one we want to solve by changing the behaviour of go/doc.Synopsis (see discussion on #59189).
The problem is that the documentation refers to "first sentence", it does so with a specific meaning as defined by go/doc.Synopsis, and not with the meaning a reader would have in mind, of natural language in whatever language the comment is written in. This can be surprising.
The solution should be for the main points of reference for learning how to document Go code to explain this better at the first instance of the phrase "first sentence", perhaps by inserting a footnote.
In https://go.dev/blog/godoc:
In https://tip.golang.org/doc/comment:
With a footnote such as:
1: The meaning of "first sentence" here is specified exactly by [go.doc/Synopsis].