Add "deprecated" to the standard library.

Add "deprecated" to the standard library.

If the editor supports it, we should have a declaration in the standard library.
I suggest a separte dart:annotation library. It may grow in the future.
Alternatively it can be put in dart:core.

R=bak@google.com

Committed: https://code.google.com/p/dart/source/detail?r=29166

[Lasse Reichstein Nielsen, 2013-10-16 14:40:32]

The optional message argument can be dropped for now, and the class made
private.

[floitsch, 2013-10-16 14:46:28]

FYI.
Not sure yet about dart:annotate.

https://codereview.chromium.org/27523002/diff/1/sdk/lib/html/html_common/html...
File sdk/lib/html/html_common/html_common_dart2js.dart (right):

https://codereview.chromium.org/27523002/diff/1/sdk/lib/html/html_common/html...
sdk/lib/html/html_common/html_common_dart2js.dart:26: const deprecated = 0;
remove.

[Brian Wilkerson, 2013-10-16 15:00:00]

> If the editor supports it, we should have a declaration in the standard
library.

The editor does support it, but because there is no declaration in the SDK we
just do a simple name matching.

> I suggest a separte dart:annotation library. It may grow in the future.
> Alternatively it can be put in dart:core.

I would like to propose that the meta package should be moved into the SDK so
that we have a standard place to define general purpose annotations, especially
annotations with tooling semantics. This is where I always wanted and intended
it to be, but I wasn't allowed to add it there because of deprecated. (And I
prefer the name dart:meta over dart:annotation, for what it's worth.)

[ahe, 2013-10-16 15:07:09]

I strongly object to adding a deprecated annotation to the Dart platform without
having it specified as a language feature.

If we want this feature in Dart, it should be decided by the language team and
specified rigorously.

There is no need to repeat the mistakes of Java which added a documentation tag
as an afterthought, but didn't provide an adequate specification or
implementation for almost a decade.

As far as I know, the language team has already decided that we do not need to
deprecated API prior to release 1.0.

[dgrove, 2013-10-16 15:10:04]

On 2013/10/16 15:07:09, ahe wrote:
> I strongly object to adding a deprecated annotation to the Dart platform
without
> having it specified as a language feature.
> 
> If we want this feature in Dart, it should be decided by the language team and
> specified rigorously.
> 
> There is no need to repeat the mistakes of Java which added a documentation
tag
> as an afterthought, but didn't provide an adequate specification or
> implementation for almost a decade.
> 
> As far as I know, the language team has already decided that we do not need to
> deprecated API prior to release 1.0.

As I've stated before, I believe that this needs to be in dart:core. I would
like to see this in place before 1.0 - we certainly will ship versions of Dart
with deprecated pieces shortly after 1.0 .

[Lasse Reichstein Nielsen, 2013-10-17 05:57:33]

On 2013/10/16 15:07:09, ahe wrote:
> I strongly object to adding a deprecated annotation to the Dart platform
without
> having it specified as a language feature.
> 
> If we want this feature in Dart, it should be decided by the language team and
> specified rigorously.

It is already here. If it needs to be specified more than what already exists,
that should happen ASAP. It hasn't happened yet, hence this CL.

> There is no need to repeat the mistakes of Java which added a documentation
tag
> as an afterthought, but didn't provide an adequate specification or
> implementation for almost a decade.

The @deprecated annotation has no runtime-semantic meaning. It is available to
tools 
that choose to use it. 
I agree that its meaning should be specified, so it's not used incorrectly. That
can
be done in the dartdoc of the annotation, and doesn't need to be in the language
specification.
The only thing that is important is that the tools understand it correctly.

> As far as I know, the language team has already decided that we do not need to
> deprecated API prior to release 1.0.

We *are* deprecating API. We need the annotation (or something similar) and we
*already have it*, just badly implemented. The need is clear and present.

We don't want to have deprecated API in the Dart standard libraries *at* the
release of 1.0, but we most definitely have it prior to that.
Also, the dart standard libraries are not necessarily the only users of
@deprecated.
The Editor supports it, and have done so for considerable time. It is already in
use.

This is a better version of what is currently being used, and by having a single
declaration that everybody can use, the editor can start recognizing it by value
instead of by name. We can disagree about what the editor should do with the 
annotation, but that does not change that we need to have it. 

We can't sit on our hands and not specify this while it is already de-facto
there,
so this is an implementation with a specification. If you have an even better
suggestion, please say how to improve it.

(Personally I'd prefer to add it to the DartDoc spec, so you write @deprecated 
inside the DartDoc, since it is really an annotation for documentation purposes,
but that never got any traction).

[Lasse Reichstein Nielsen, 2013-10-17 06:00:52]

On 2013/10/16 15:00:00, Brian Wilkerson wrote:
> The editor does support it, but because there is no declaration in the SDK we
> just do a simple name matching.

I know. That's one of the reasons I want to add a single, centralized
declaration,
to avoid the name matching. 
Neither you nor users haven't had a way to do it properly.

> > I suggest a separte dart:annotation library. It may grow in the future.
> > Alternatively it can be put in dart:core.
> 
> I would like to propose that the meta package should be moved into the SDK so
> that we have a standard place to define general purpose annotations,
especially
> annotations with tooling semantics. This is where I always wanted and intended
> it to be, but I wasn't allowed to add it there because of deprecated. (And I
> prefer the name dart:meta over dart:annotation, for what it's worth.)

I can live with dart:meta.
I can live with putting it in dart:core.
Having it in package:meta doesn't seem to work.
Not having isn't really an option.

[kevmoo-old, 2013-10-17 11:39:33]

DBC

See https://code.google.com/p/dart/issues/detail?id=6773 :: package:meta ->
dart:meta

Although I'm happy with dart:annotation

+1 for having all annotations supported by the editor in dart:*

[Sean Eagan, 2013-10-18 14:14:10]

On 2013/10/16 14:40:32, Lasse Reichstein Nielsen wrote:
> The optional message argument can be dropped for now, and the class made
> private.

If we fix http://dartbug.com/13582 then we don't need a separate constant from
the class in the first place.

If not fixed, and the class is made public later, it will be a common source of
errors, as many people will instinctively use:

@Deprecated

instead of:

@Deprecated()
@deprecated

which will be incorrect, but will not produce a warning or error since it would
still be a valid annotation.

[Lasse Reichstein Nielsen, 2013-10-23 14:30:03]

Moved annotations to dart:core.

Keep it simple: No parameters, just a single constant. Extra documentation
should be put in the DartDoc for the deprecated method.

Added documentation specifying the intended meaning of the annotations.

[ahe, 2013-10-23 14:32:54]

https://codereview.chromium.org/27523002/diff/51001/sdk/lib/core/annotations....
File sdk/lib/core/annotations.dart (right):

https://codereview.chromium.org/27523002/diff/51001/sdk/lib/core/annotations....
sdk/lib/core/annotations.dart:74: const override = const _Override();
This is not OK. You need explicit approval from the language team to do this.

We have previously discussed adding @override to Dart, but didn't want to do so
because we didn't want to encourage style guides which insist on using @override
in all place where it is possible.

This is an abomination.

[gbracha, 2013-10-23 21:29:20]

AFICR, we decided at the last language meeting that we would have a class
Deprecated to which we can add const constructors as needed.  Please coordinate
with Lars and Kasper on this.

[Lasse Reichstein Nielsen, 2013-10-24 07:49:57]

I believe Peter's opposition is mainly wrt. @override.
Should I move that back to package:meta?

[Lasse Reichstein Nielsen, 2013-10-24 10:42:02]

Now exposes Deprecated as constructor, per discussion with language team.

[bakster, 2013-10-24 10:55:24]

LGTM,
  Lars

https://codereview.chromium.org/27523002/diff/121001/sdk/lib/core/annotations...
File sdk/lib/core/annotations.dart (right):

https://codereview.chromium.org/27523002/diff/121001/sdk/lib/core/annotations...
sdk/lib/core/annotations.dart:72: String toString() => "Deprecated until
$expires";
"Deprecated feature. Will be removed $expires"

[Lasse Reichstein Nielsen, 2013-10-24 11:47:12]

Committed patchset #6 manually as r29166 (presubmit successful).