8145461: finalize and integrate @Deprecated annotation specification change

Reviewed-by: scolebourne, chegar, lancea
This commit is contained in:
Stuart Marks 2016-04-11 11:45:30 -07:00
parent 70dbeeb6df
commit 4544652494

@ -29,14 +29,44 @@ import java.lang.annotation.*;
import static java.lang.annotation.ElementType.*;
/**
* A program element annotated @Deprecated is one that programmers
* are discouraged from using, typically because it is dangerous,
* or because a better alternative exists. Compilers warn when a
* deprecated program element is used or overridden in non-deprecated code.
* A program element annotated {@code @Deprecated} is one that programmers
* are discouraged from using. An element may be deprecated for any of several
* reasons, for example, its usage is likely to lead to errors; it may
* be changed incompatibly or removed in a future version; it has been
* superseded by a newer, usually preferable alternative; or it is obsolete.
*
* <p>Use of the &#64;Deprecated annotation on a local variable
* declaration or on a parameter declaration or a package declaration
* has no effect on the warnings issued by a compiler.
* <p>Compilers issue warnings when a deprecated program element is used or
* overridden in non-deprecated code. Use of the {@code @Deprecated}
* annotation on a local variable declaration or on a parameter declaration
* or a package declaration has no effect on the warnings issued by a compiler.
*
* <p>This annotation type has a string-valued element {@code since}. The value
* of this element indicates the version in which the annotated program element
* was first deprecated.
*
* <p>This annotation type has a boolean-valued element {@code forRemoval}.
* A value of {@code true} indicates intent to remove the annotated program
* element in a future version. A value of {@code false} indicates that use of
* the annotated program element is discouraged, but at the time the program
* element was annotated, there was no specific intent to remove it.
*
* @apiNote
* It is strongly recommended that the reason for deprecating a program element
* be explained in the documentation, using the {@code @deprecated}
* javadoc tag. The documentation should also suggest and link to a
* recommended replacement API, if applicable. A replacement API often
* has subtly different semantics, so such issues should be discussed as
* well.
*
* <p>It is recommended that a {@code since} value be provided with all newly
* annotated program elements. Note that {@code since} cannot be mandatory,
* as there are many existing annotations that lack this element value.
*
* <p>There is no defined order among annotation elements. As a matter of
* style, the {@code since} element should be placed first.
*
* <p>The {@code @Deprecated} annotation should always be present if
* the {@code @deprecated} javadoc tag is present, and vice-versa.
*
* @author Neal Gafter
* @since 1.5
@ -46,4 +76,23 @@ import static java.lang.annotation.ElementType.*;
@Retention(RetentionPolicy.RUNTIME)
@Target(value={CONSTRUCTOR, FIELD, LOCAL_VARIABLE, METHOD, PACKAGE, PARAMETER, TYPE})
public @interface Deprecated {
/**
* Returns the version in which the annotated element became deprecated.
* The version string is in the same format and namespace as the value of
* the {@code &#64;since} javadoc tag. The default value is the empty
* string.
*
* @return the version string
* @since 9
*/
String since() default "";
/**
* Indicates whether the annotated element is subject to removal in a
* future version. The default value is {@code false}.
*
* @return whether the element is subject to removal
* @since 9
*/
boolean forRemoval() default false;
}