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

doc: document the "Deprecated" convention #10909

Closed
minux opened this issue May 19, 2015 · 16 comments
Closed

doc: document the "Deprecated" convention #10909

minux opened this issue May 19, 2015 · 16 comments
Milestone

Comments

@minux
Copy link
Member

minux commented May 19, 2015

Perhaps in effective go. Also worth mention in go1.5.html?

see https://groups.google.com/forum/#!topic/golang-dev/ya5vE0G62Z4.

@minux minux added this to the Go1.5 milestone May 19, 2015
@robpike
Copy link
Contributor

robpike commented May 19, 2015

In go1.5.html yes, in Effective Go, no.

@adg
Copy link
Contributor

adg commented May 19, 2015

But go1.5.html is a changelog. We should document the convention itself
somewhere. In the godoc docs?

On 19 May 2015 at 15:57, Rob Pike notifications@github.com wrote:

In go1.5.html yes, in Effective Go, no.


Reply to this email directly or view it on GitHub
#10909 (comment).

@robpike
Copy link
Contributor

robpike commented May 19, 2015

Seems like a better place. Or maybe we need a general conventions, or document conventions, document.

@minux
Copy link
Member Author

minux commented May 19, 2015 via email

@rsc rsc modified the milestones: Go1.6, Go1.5 Aug 5, 2015
dmitshur referenced this issue in gomodule/redigo Aug 31, 2015
@dmitshur
Copy link
Contributor

What is the final convention that was decided on? It's really hard to conclusively parse it out of the linked thread even after reading all messages.

Edit: I think the answer lies in this message:

Please see https://golang.org/cl/10188.
I hope I've found all the cases.

@minux
Copy link
Member Author

minux commented Aug 31, 2015

Please see https://golang.org/cl/10188 for examples.

There are three forms:

  1. inlined form
    type T struct {
    FieldA int32 // Deprecated: use FieldB instead.
    FieldB int64
    }

  2. long form 1, used with entities lacking docs
    // Deprecated: T is deprecated.
    type T struct {
    // Deprecated: for backward compatibility FieldC is still populated,
    // but new code should use FieldD instead.
    FieldC int32

    FieldD int64
    }

  3. long form 2, used for entities with docs
    // Do fires the missiles.
    //
    // Deprecated: missiles supplies depleted. Do is a no-op now.
    func Do() error

@dmitshur
Copy link
Contributor

I have a question. Would it be better or worse if "Deprecated:" was made mandatory to be the first word of a doc comment for a deprecated field/variable/func/method? That seems like the first thing the documentation should convey, and having it be something other than the first word means a user is possibly going to spend some time reading/learning about a new method before realizing that it's already deprecated.

Consider the 3rd example above:

// Do fires the missiles.
//
// Deprecated: missiles supplies depleted. Do is a no-op now.
func Do() error

A user would need to read all of "Do fires the missiles." or however long that comment is, while spending energy understanding the functionality, only then to hopefully get to the next paragraph that says it's deprecated and they should be reading about something else instead.

I had this thought on my mind and just wanted to share it.

@dmitshur
Copy link
Contributor

A better real-world example where the problem is worse can be seen here:

// StringSlicePtr converts a slice of strings to a slice of pointers
// to NUL-terminated byte arrays. If any string contains a NUL byte
// this function panics instead of returning an error.
//
// Deprecated: Use SlicePtrFromStrings instead.
func StringSlicePtr(ss []string) []*byte {

@adg
Copy link
Contributor

adg commented Oct 12, 2015

I don't really like the idea of putting the word "Deprecated" first. With
the current scheme, it's nice that the reason for the deprecation appears
after "Deprecated:".

But perhaps godoc should be made to hide or collapse the definitions of
deprecated functions, and to highlight the word "Deprecated" in bold and/or
red. WDYT?

On 12 October 2015 at 11:21, Dmitri Shuralyov notifications@github.com
wrote:

A better real-world example where the problem is worse can be seen here:

// StringSlicePtr converts a slice of strings to a slice of pointers// to NUL-terminated byte arrays. If any string contains a NUL byte// this function panics instead of returning an error.//// Deprecated: Use SlicePtrFromStrings instead.func StringSlicePtr(ss []string) []*byte {


Reply to this email directly or view it on GitHub
#10909 (comment).

@dmitshur
Copy link
Contributor

With the current scheme, it's nice that the reason for the deprecation appears
after "Deprecated:".

I agree, that should be preserved. The way I imagined it would be:

// Deprecated: Use SlicePtrFromStrings instead.
//
// StringSlicePtr converts a slice of strings to a slice of pointers
// to NUL-terminated byte arrays. If any string contains a NUL byte
// this function panics instead of returning an error.
func StringSlicePtr(ss []string) []*byte {

I don't really like the idea of putting the word "Deprecated" first.

Do you still dislike it even given the above? If so, that's completely okay. I just wanted to mention minor idea so that it would be considered.

But perhaps godoc should be made to hide or collapse the definitions of
deprecated functions, and to highlight the word "Deprecated" in bold and/or
red.

Perhaps it (and many other Go editors/tools) can/should do that. But I think that's an orthogonal optional enhancement.

I realize requiring "Deprecated:" to come first will require an update to golint which currently checks that comments begin with "// {{.IdenitiferName}} ...".

@adg
Copy link
Contributor

adg commented Oct 13, 2015

That does seem reasonable. I don't have strong feelings one way or another.

@rsc
Copy link
Contributor

rsc commented Nov 5, 2015

I'm sorry, but breaking the rules about how doc comments begin is off the table.

@dmitshur
Copy link
Contributor

dmitshur commented Nov 5, 2015

No problem, thanks for considering it!

In that case, existing tools can choose to detect deprecated methods and visually warn users about that, if they deem that to be an improvement/worth doing.

@adg adg self-assigned this Jan 27, 2016
@gopherbot
Copy link

CL https://golang.org/cl/18956 mentions this issue.

@mibk
Copy link
Contributor

mibk commented May 2, 2016

But perhaps godoc should be made to hide or collapse the definitions of
deprecated functions, and to highlight the word "Deprecated" in bold and/or
red. WDYT?

Have you been considering emphasizing the deprecated stuff in godoc ever since? As an
alternative solution the strike-through format could be used.

FiloSottile referenced this issue in beevik/ntp Oct 2, 2017
Now that we have QueryWithOptions, TimeV isn't necessary.
@FiloSottile
Copy link
Contributor

I created https://golang.org/wiki/Deprecated to have something to link to.

gopherbot pushed a commit to golang/website that referenced this issue May 26, 2021
…godoc post

Fixes golang/go#10909

Change-Id: Ie2553bc2f6983cbcaf7398366c21dc175e1f5453
Reviewed-on: https://go-review.googlesource.com/18956
Reviewed-by: Rob Pike <r@golang.org>
X-Blog-Commit: 257114af91a0defb1fc2c16c7f4ae2429b8a4e0f
@rsc rsc unassigned adg Jun 23, 2022
passionSeven added a commit to passionSeven/website that referenced this issue Oct 18, 2022
…godoc post

Fixes golang/go#10909

Change-Id: Ie2553bc2f6983cbcaf7398366c21dc175e1f5453
Reviewed-on: https://go-review.googlesource.com/18956
Reviewed-by: Rob Pike <r@golang.org>
X-Blog-Commit: 257114af91a0defb1fc2c16c7f4ae2429b8a4e0f
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

No branches or pull requests

8 participants