8145461: finalize and integrate @Deprecated annotation specification change
Reviewed-by: scolebourne, chegar, lancea
This commit is contained in:
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 @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 @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;
|
||||
}
|
||||
|
Loading…
x
Reference in New Issue
Block a user