Gray out deprecated symbols

[rakyll]

If an exported symbol is deprecated, its godoc should be grayed out. Currently, there is no highlighting for deprecated symbols and users cannot easily they are depending on the legacy APIs.

[zombiezen]

Haha, this is exactly the bug I was going to file. 👍

[dmitshur]

Implementation-wise, I see this being two parts.

First one is some general Go code to determine when a symbol is deprecated. It would have to match the rules that are set out for deprecating a symbol. Reference for that is here:

To signal that an identifier should not be used, add a paragraph to its doc comment that begins with "Deprecated:" followed by some information about the deprecation.

That should be relatively easy to implement, but does anyone know if this already exists anywhere?

Second part is making use of that to change presentation of such symbols on godoc.org.

[rakyll]

Standard library and official packages use the "Deprecated:" notation, see "ErrWriteAfterFlush" at https://golang.org/pkg/net/http/ for an example. grep the Go tree for more examples.

As an example of a standalone deprecated symbol, see https://golang.org/pkg/net/http/#Transport.CancelRequest.