x/pkgsite: shouldn't consider "e.g." a sentence ender when getting first line of a doc string

[golightlyb]

What did you do?

Publish a module on pkg.go.dev with subfolders, one containing a file with a docstring like so:

// somemodule/foo/foo.go

// Package foo does bar e.g. by barring a foo. It also frobulates a fizzbuzz.
package foo

What did you expect to see?

The "#section-directories" anchor for the main page for the module on the website should list the subfolders like this:

foo | Package foo does bar e.g. by barring a foo.

What did you see instead?

The description is truncated like this:

foo | Package foo does bar e.g.

---

Notes

A proper implementation would handle other separators such as "i.e.", and documentation written in other languages etc. w.r.t. Unicode® Standard Annex #29: Unicode Text Segmentation: Sentence Boundaries. One challenge is that the locale would probably have to be guessed as it isn't set in documentation explicitly anywhere.

[thediveo]

a work around could be e.g. "for instance"?

[findleyr]

IIRC pkgsite uses go/doc.Synopsis, so it probably makes sense to promote this to a request for go/doc.

[golightlyb]

IIRC pkgsite uses go/doc.Synopsis, so it probably makes sense to promote this to a request for go/doc.

Good point. I hadn't considered the other places where this is visible. Given the documentation of that function, this seems working as specified and documented, so if the behaviour is going to change I guess this has to go through the full proposal process.

[findleyr]

With that said, go/doc.Synopsis currently has clear, simple semantics. We may not be able to change those semantics without breaking compatibility. Even if we could, I don't think supporting this use-case is worth the loss of simplicity.

In summary:

• pkgsite should use go/doc.Synopsis, because go documentation is consumed my many tools and doc authors need to be able to follow one single style that works for all tools.
• Evenif go/doc could change, I don't think it should add support for edge cases, especially those that are specific to one language or locale. Better to keep things simple.

go/doc is a contract that package authors can use to control the structure of their documentation in various tools. The contract is clear about the meaning of periods: "That sentence ends after the first period followed by space and not preceded by exactly one uppercase letter". Therefore, I think the correct solution here is to rephrase the sentence.

[golightlyb]

Inclined to agree, yeah. I think the documentation of the function itself is fine, but needs pointing to.

I think the following two sentences in the documentation, which are the main reference points for learning about Go doc comments, could do with 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].

I'm going to close this issue and open one for x/website instead. Thanks for the replies!