JDK 9 RFR of 6481080 : (ann) @Deprecated annotation has no effect on packages

[joe darcy]

Hello,

As part of cleaning up the deprecation facility in 9, please review this 
change to document when a @Deprecated annotation is a no-op:

     6481080 : (ann) @Deprecated annotation has no effect on packages
     http://cr.openjdk.java.net/~darcy/6481080.0/

Since the @Deprecated feature was added in 5, it was a no-op on local 
variables, parameters, and packages. The JLS documented the no-op 
situation for local variables and parameters; separately, Alex will 
handle updating the JLS in 9 to state packages are a no-op too.

Patch to java.lang.Deprecated below; the patch also fixes a typo in the 
JLS section number.

Thanks,

-Joe

--- old/src/java.base/share/classes/java/lang/Deprecated.java 2015-01-06 
15:06:40.893641309 -0800
+++ new/src/java.base/share/classes/java/lang/Deprecated.java 2015-01-06 
15:06:40.737641309 -0800
@@ -1,5 +1,5 @@
  /*
- * Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights 
reserved.
+ * Copyright (c) 2003, 2015, Oracle and/or its affiliates. All rights 
reserved.
   * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   *
   * This code is free software; you can redistribute it and/or modify it
@@ -34,9 +34,13 @@
   * or because a better alternative exists.  Compilers warn when a
   * deprecated program element is used or overridden in non-deprecated 
code.
   *
+ * <p>Use of the @Deprecated annotation on a local variable
+ * declaration or on a parameter declaration or a package declaration
+ * has no effect.
+ *
   * @author  Neal Gafter
   * @since 1.5
- * @jls 9.6.3.6 @Deprecated
+ * @jls 9.6.4.6 @Deprecated
   */
  @Documented
  @Retention(RetentionPolicy.RUNTIME)