Deprecation syntax proposal

[Sergey Ignatov]

Hi all,

We have an issue (https://github.com/go-lang-plugin-org/go-lang-idea-plugin/issues/1556) about supporting a special syntax highlighting for deprecated symbols. As far as I understand at the moment there is no a standard way to markup it.

Will be cool to introduce a simple syntax for that:

//go:deprecated This package has been deprecated, use OtherPackage instead.

package MyPackage

//go:deprecated This function has been deprecated, use MyOtherFun instead

func MyFunc() {}

type MyType struct {

    //go:deprecated Use FirstName instead

    Name string 

    FirstName string

}

Thoughts?

[Russ Cox]

On Tue, May 5, 2015 at 7:22 AM, Sergey Ignatov <igna...@gmail.com> wrote:

We have an issue (https://github.com/go-lang-plugin-org/go-lang-idea-plugin/issues/1556) about supporting a special syntax highlighting for deprecated symbols. As far as I understand at the moment there is no a standard way to markup it.

Thanks for starting a thread. There are a couple constraints here that I think narrow the design space down quite a bit.

First, the annotation should be in a comment (as opposed to new syntax), since we want to keep code readable by tools that don't know about the details of this annotation. We've already done this enough that this decision is implicit in your proposal; I just wanted to say it explicitly.

Second, the annotation should not compromise or replace existing documentation comments. Even when something is deprecated, it is important for it to have documentation about how it works. For example, if you need to debug code that uses it, you'd still want to know what it is supposed to do.

This leads to basically two choices: a separate comment above the doc comment (because there cannot be anything between the doc comment and the declaration), or some syntax within the doc comment itself. We have used the separate comment approach for compiler directives like //go:noescape, because that doesn't make sense to see in documentation. The deprecated idea is something you do want to see in documentation, so I would imagine we're looking at syntax within the doc comment itself.

The form of the beginning of a doc comment is well defined already (http://golang.org/doc/effective_go.html#commentary); placing the deprecation note at the beginning would break that convention and require retooling anything that uses that sentence as a summary. Therefore the deprecation note should probably not come at the beginning of the doc comment.

That leaves the rest of the doc comment, with the obvious default place being the end. But as long as the rule is general, people can place the note wherever it makes most sense in the flow.

Now we're talking about some kind of notation at within the doc comment to mark that something is deprecated. In general the doc comment formatting rules have been chosen so that doc comments viewed in the program itself look like natural text, not like markup. That argues against a token like //go:deprecate, but you do want something that's not going to come up accidentally. 

Based on all this, my suggestion would be to define that you take the doc comment, break it into paragraphs by splitting at blank lines, and look for a paragraph beginning with "Deprecated:". If one exists, the API is deprecated, and the rest of the paragraph (at least) explains perhaps why and what to use instead. In this way, the plugin can provide special processing but tools like godoc need not change at all.

For example:

// MyFunc fires all the missiles.

//

// Deprecated: Due to budget cuts, there are no missiles.

// MyFunc is now a no-op and should no longer be called.

//

// More information about MyFunc might go here.

func MyFunc()

// A MyType is a database record describing a person.

type MyType struct {

    // Name is the person's name.

    //

    // Deprecated: There is confusion in the existing records about whether

    // name is the full name or just the first name. Use FirstName or FullName instead.

    Name string

    // FirstName is the person's first name, for use in the salutation in a form letter.

    FirstName string

     // FullName is the person's full name, for use in address labels.

     FullName string

}

Russ

[Sergey Ignatov]

Agreed. Looks good for us.

[bronz...@gmail.com]

Agreed. A standard way is enough for me.

If I can choose it, I may choose following syntax:

// MyFunc fires all the missiles.

//

// @deprecated Due to budget cuts, there are no missiles. MyFunc is now a no-op and should no longer be called.

//

// More information about MyFunc might go here.

func MyFunc()

 

It is compatible with php & java. 

It is easier to see from a lot of code. 

It is easier to grep from a lot of source code.

It is easier to find it from ast use golang to develop a tool to support it.

[Rob Pike]

No at signs please. This isn't Java and the word Deprecated is clear and greppable enough.

-rob

--
You received this message because you are subscribed to the Google Groups "golang-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to golang-dev+...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[andrewc...@gmail.com]

vet is a probably a decent tool to check for this.

[Robert Griesemer]

Late to this discussion but perhaps it should be

DEPRECATED rather then Deprecated ?

In style with BUG, TODO, etc. ?

As an aside, godoc already has a flag (-notes) that permits the extraction of such comments.

- gri

--

[Russ Cox]

On Tue, May 12, 2015 at 2:28 PM, Robert Griesemer <g...@golang.org> wrote:

Late to this discussion but perhaps it should be

DEPRECATED rather then Deprecated ?

In style with BUG, TODO, etc. ?

I think I'd still lean toward "Deprecated:". It's a little too long to shout, and there's not an associated user name like for TODO and BUG. For that matter, I don't believe we currently put TODOs in doc comments (at least I hope we don't), and I think the per-package BUGS section was probably a mistake (mine) that maybe we should retire at some point in favor of something like a "Warning:" section in the relevant not-package-scoped doc comment. The problem with BUG is that it shows up at the end of the package doc even though they're usually about specific functions.

Russ

[Andrew Gerrand]

On 14 May 2015 at 04:24, Russ Cox <r...@golang.org> wrote:

I think I'd still lean toward "Deprecated:".

I agree. It's a hard word to miss at the beginning of a new paragraph, and if we feel it's not obvious enough we could have godoc embolden it in its HTML view for emphasis.

[Rob Pike]

Someone will spell it "Depreciated" and wonder why everyone is still using their function. So be it, "Deprecated" is the right word and right emphasis.

It's almost as if the word already existed.

-rob

--

[Ian Davis]

On Thu, May 14, 2015, at 02:24 AM, Rob Pike wrote:

Someone will spell it "Depreciated" and wonder why everyone is still using their function. So be it, "Deprecated" is the right word and right emphasis.

 

That would be appropriate if it wasn't fully deprecated, just reduced in value by the presence of another function :)

 

 

[Russ Cox]

On Wed, May 13, 2015 at 11:18 PM, zuxiong lin <linzuxi...@gmail.com> wrote:

I think  

// @Deprecated  This API is bad performance.

is more distinguishable .

Quoting my first response, "In general the doc comment formatting rules have been chosen so that doc comments viewed in the program itself look like natural text, not like markup."

This thread is not about changing a fundamental decision like that.

Russ

[zuxiong lin]

I think  

// @Deprecated  This API is bad performance.

is more distinguishable .

Or 

@Deprecated
// It is not used in the future .
func add() {
  //
}

Although you do not think  It is not good enough from Java-Style.

[andrewc...@gmail.com]

It isn't an email address. "at Depricated" doesn't mean anything.

[andrewc...@gmail.com]

let the misspellings begin.

[Rob Pike]

What about @Depilated or #Decimated or %Deracinated?

-rob

[andrewc...@gmail.com]

It is clear to me "N.B. Deprecated" is the only suitable marker. Full Latin spelling optional.

[Rob Pike]

I am dyspeptic.

-rob

[bronz...@gmail.com]

It looks like go source is using some deprecated mark.

http://golang.org/src/go/doc/doc.go#L21

On Tuesday, May 5, 2015 at 11:55:44 PM UTC+8, rsc wrote:

[Russ Cox]

Yes, there have been many ad-hoc solutions. Now we have a canonical one.

--

[minux]

On May 18, 2015 10:40 AM, "Russ Cox" <r...@golang.org> wrote:
>
> Yes, there have been many ad-hoc solutions. Now we have a canonical one.

Should we update the code to use the new convention?

[Russ Cox]

Sure.

[minux]

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

I hope I've found all the cases.

[Damian Gryski]

Should http://golang.org/doc/effective_go.html#commentary be updated to mention this?

Damian

[minux]

On Tue, May 19, 2015 at 1:18 AM, Damian Gryski <dgr...@gmail.com> wrote:

Should http://golang.org/doc/effective_go.html#commentary be updated to mention this?

Yes, this task is left to others more adept at writing docs.

I've filed #10909 to remind us.