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

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

Closed
golightlyb opened this issue Mar 23, 2023 · 5 comments

Comments

@golightlyb
Copy link
Contributor

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.

@gopherbot gopherbot added this to the Unreleased milestone Mar 23, 2023
@thediveo
Copy link

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

@findleyr
Copy link
Contributor

findleyr commented Mar 23, 2023

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

@golightlyb
Copy link
Contributor Author

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

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
Copy link
Contributor Author

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!

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

No branches or pull requests

4 participants