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

Gray out deprecated symbols #456

Open
rakyll opened this Issue Nov 7, 2016 · 3 comments

Comments

Projects
None yet
3 participants
@rakyll
Member

rakyll commented Nov 7, 2016

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

This comment has been minimized.

Show comment
Hide comment
@zombiezen

zombiezen Nov 7, 2016

Member

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

Member

zombiezen commented Nov 7, 2016

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

@dmitshur

This comment has been minimized.

Show comment
Hide comment
@dmitshur

dmitshur Nov 8, 2016

Member

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.

Member

dmitshur commented Nov 8, 2016

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

This comment has been minimized.

Show comment
Hide comment
@rakyll

rakyll Nov 8, 2016

Member

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.

Member

rakyll commented Nov 8, 2016

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment