Skip to content

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

Closed
@ChrisHines

Description

@ChrisHines

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://go.dev/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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    DocumentationIssues describing a change to documentation.NeedsFixThe path to resolution is known, but the work has not been done.website

    Type

    No type

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions