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/tools/godoc, go.dev: URL at end of sentence inside brackets causes trailing period to get incorrectly included in the URL #37640

Open
ShawnROGrady opened this issue Mar 3, 2020 · 6 comments
Labels
NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. pkgsite Tools This label describes issues relating to any tools in the x/tools repository.
Milestone

Comments

@ShawnROGrady
Copy link

ShawnROGrady commented Mar 3, 2020

The link in the documentation for the Mutex.Lock() method includes a trailing period. This results in a 404 page when clicked. Inspecting the source, the attribute of interest is:

<a href="https://golang.org/issue/20803.">https://golang.org/issue/20803.</a> 

The fix for this should just be to remove the trailing period in the comment used to generate the documentation, which is what is being done elsewhere.

@gopherbot
Copy link

Change https://golang.org/cl/221937 mentions this issue: cmd/go/internal/lockedfile: remove trailing period for godoc

@dmitshur dmitshur added the NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. label Mar 3, 2020
@dmitshur
Copy link
Contributor

dmitshur commented Mar 3, 2020

Thanks for reporting.

We should see if this can be fixed in godoc instead. The text in the documentation seems valid. It's a sentence that ends with a period, and a URL happens to be at the end of that sentence. The sentence is inside round brackets.

I suspect the round brackets are making it not recognize the period at the end of a sentence.

If we can fix this in godoc, that means a lot of Go documentation doesn't have to change to avoid this pitfall. I suspect there's more code in the wild that has a similar pattern.

The issue is currently happening at https://pkg.go.dev/cmd/go/internal/lockedfile and https://golang.org/pkg/cmd/go/internal/lockedfile/ as well.

@dmitshur dmitshur added this to the Backlog milestone Mar 3, 2020
@dmitshur
Copy link
Contributor

dmitshur commented Mar 3, 2020

which is what is being done elsewhere

Can you point out where you're referring to?

@ShawnROGrady
Copy link
Author

@dmitshur I misspoke about this being done elsewhere, I had noticed other places where we didn't include the trailing period when referencing an issue in a comment (such as src/cmd/go/internal/lockedfile/internal/filelock/filelock_fcntl.go:16) but didn't realize that they weren't being included in the documentation.

@dmitshur
Copy link
Contributor

dmitshur commented Mar 3, 2020

Thanks for clarifying.

@dmitshur dmitshur changed the title cmd/go/internal/lockedfile: trailing period on URL leads to 404 x/tools/godoc, go.dev: URL at end of sentence inside brackets causes trailing period to get incorrectly included in the URL Mar 3, 2020
@gopherbot gopherbot added the Tools This label describes issues relating to any tools in the x/tools repository. label Mar 3, 2020
@bcmills bcmills added the pkgsite label Mar 4, 2020
@gopherbot
Copy link

Change https://golang.org/cl/221940 mentions this issue: go/doc: update url matcher to exclude trailing chars

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. pkgsite Tools This label describes issues relating to any tools in the x/tools repository.
Projects
None yet
Development

No branches or pull requests

4 participants