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

[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://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.