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/website: "Go Doc Comments" does not explain deprecation notices #55083

Open
ChrisHines opened this issue Sep 15, 2022 · 0 comments
Open

x/website: "Go Doc Comments" does not explain deprecation notices #55083

ChrisHines opened this issue Sep 15, 2022 · 0 comments
Labels
Documentation NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. website
Milestone

Comments

@ChrisHines
Copy link
Contributor

ChrisHines commented Sep 15, 2022

Does this issue reproduce with the latest release?

Yes

What did you do?

Tried to find the documentation for the correct way to add a deprecation notice to a doc comment.

What did you expect to see?

I expected to find it in the new Go Doc Comments document.

What did you see instead?

It's not there.

The most helpful "official" reference is on the wiki at https://github.com/golang/go/wiki/Deprecated. I found that by reading the original issue (#10909) about documenting the convention. That issue also reminded me that the old (pre Go 1.0) blog post about doc comments had been updated to explain deprecation notices. That blog post now starts with a note directing readers to the new "Go Doc Comments" document, which might dissuade them from reading the rest of the blog post and missing the info about deprecation notices.

Recommended Solution

It seems to me that we should add a section about deprecation notices to the Go Doc Comments document.

@gopherbot gopherbot added this to the Unreleased milestone Sep 15, 2022
@dle8 dle8 modified the milestones: Unreleased, website/later Sep 16, 2022
@cherrymui cherrymui added Documentation NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. labels Sep 19, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Documentation NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. website
Projects
None yet
Development

No branches or pull requests

4 participants