doc: document the "Deprecated" convention

[minux]

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

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

[robpike]

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

[adg]

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]

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

[minux]

I like the idea of a document conventions docs.

[dmitshur]

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]

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]

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]

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]

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]

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]

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

[rsc]

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

[dmitshur]

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.

[gopherbot]

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

[mibk]

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]

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