Do both @Deprecated and @deprecated metadata annotations exist ?

[marcmcd]

Page URL

https://dart.dev/language/metadata.html

Page source

https://github.com/dart-lang/site-www/tree/main/src/language/metadata.md

Describe the problem

The text "Three annotations are available to all Dart code: @Deprecated, @deprecated, and @override."
refers to the @Deprecated and @deprecated annotations. Do both of these exist?
Other web Dart metadata references do not
mention the @Deprecated annotation but do mention the @required or the @proxy annotations as
being available to all Dart code.

Expected fix

Replace "Three annotations are available to all Dart code: @Deprecated, @deprecated, and @override."
with"Three annotations are available to all Dart code: @deprecated, @override, and @required."
or
Replace "Three annotations are available to all Dart code: @Deprecated, @deprecated, and @override."
with "Three annotations are available to all Dart code: @deprecated, @override, and @proxy."

Then replace all occurrences of @Deprecated with @deprecated in the remaining text.

Additional context

No response

[parlough]

Hey @marcmcd, thanks for opening an issue!

@Deprecated is an available annotation in dart:core and is actually suggested over @deprecated as it allows you to specify a deprecation message. You can learn more on the Deprecated API docs.

As for @required, it is an annotation present in package:meta (API docs), before sound null safety. It is however no longer used as required is a built-in keyword in Dart 2.12 and later.

As for @proxy, that was an old annotation from Dart 1 that is no longer part of Dart. I'm curious where you saw this, as any mention to it should likely be updated.

---

Does that provide the information you are looking for? So Deprecated, @deprecated, and @override should still be the three annotations available in dart:core. There is also @pragma, but it generally shouldn't be needed by users.

With this information, do you think we could improve the page or make it clearer? Should we link to the API docs for each annotation on the page?

Let us know. Thanks again for question and the details!

[marcmcd]

Hi Parker,

Thanks for the quick response.
That clears things up for me.

"As for @proxy, that was an old annotation from Dart 1 that is no longer part of Dart.
I'm curious where you saw this, as any mention to it should likely be updated."

I found that reference to @proxy here:
https://stackoverflow.com/questions/23476800/what-does-do-in-dart-programs
that post is over 9 years old, so as far as I know, nothing currently needs to be updated to remove @proxy

With this information, do you think we could improve the page or make it clearer?
Should we link to the API docs for each annotation on the page?

How about adding the text in bold italics below ? You can leave out the @deprecated example for brevity.

--------------------------------------------------------- 8< ---------------------------------------------------------
Metadata

Use metadata to give additional information about your code. A metadata annotation begins with
the character @, followed by either a reference to a compile-time constant (such as deprecated)
or a call to a constant constructor.

Three annotations are available to all Dart code: @Deprecated, @deprecated, and @override.
For examples of using @override, see Extending a class. Here’s an example of using the
@Deprecated annotation:

class Television { /// Use [turnOn] to turn the power on instead. @Deprecated('Use turnOn instead') void activate() { turnOn(); }

/// Turns the TV's power on.
void turnOn() {...}
// ···
}


The @deprecated annotation is used to indicate code that will be removed
in the next release with no alternative code provided, it is equivalent to

@Deprecated('next release')

For example:

@deprecated
void shimCall() {
// ···
}

You can define your own metadata annotations. Here’s an example of defining a @Todo
annotation that takes two arguments:

class Todo { final String who; final String what;

const Todo(this.who, this.what);
}


And here’s an example of using that @Todo annotation:

@Todo('Dash', 'Implement this function') void doSomething() { print('Do something'); }

Metadata can appear before a library, class, typedef, type parameter, constructor,
factory, function, field, parameter, or variable declaration and before an import
or export directive. You can retrieve metadata at runtime using reflection.

⟨  Comments                                                                          Libraries  ⟩

--------------------------------------------------------- 8< ---------------------------------------------------------

Regards,
Marc McDougall

[parlough]

I'm glad that cleared things up and thanks for providing some specific suggestions! :D

We actually always recommend to specify a message with @Deprecated, so any mention of just @deprecated should be light.

I opened #5169 with a potential solution. Consider taking a look :)

[marcmcd]

Hi Parker,
I like your changes, thanks for helping me participate in the Dart documentation. Over and out.

[parlough]

Thank you! 🫡