JDK RFR of 6556996: (ann spec) SuppressWarnings strings should be documented
Joe Darcy
joe.darcy at oracle.com
Fri Feb 22 01:46:12 UTC 2013
Hello,
Please review the simple fix below for
6556996: (ann spec) SuppressWarnings strings should be documented
http://bugs.sun.com/view_bug.do?bug_id=6556996
the webrev is at
http://cr.openjdk.java.net/~darcy/6556996.0/
and the patch is below. In brief, the only required string to be
recognized in the SuppressWarnings annotation is "unchecked", which has
been required by the JLS since Java SE 5. I made that adjustment to the
documentation of the SuppressWarnings type. In addition, I added more
@jls links relating the documentation of various annotation type to the
JLS sections which discuss them.
Thanks,
-Joe
--- old/src/share/classes/java/lang/Deprecated.java 2013-02-21
17:37:08.000000000 -0800
+++ new/src/share/classes/java/lang/Deprecated.java 2013-02-21
17:37:08.000000000 -0800
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2003, 2010, Oracle and/or its affiliates. All rights
reserved.
+ * Copyright (c) 2003, 2013, 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
@@ -36,6 +36,7 @@
*
* @author Neal Gafter
* @since 1.5
+ * @jls 9.6.3.6 @Deprecated
*/
@Documented
@Retention(RetentionPolicy.RUNTIME)
--- old/src/share/classes/java/lang/Override.java 2013-02-21
17:37:09.000000000 -0800
+++ new/src/share/classes/java/lang/Override.java 2013-02-21
17:37:09.000000000 -0800
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2003, 2011, Oracle and/or its affiliates. All rights
reserved.
+ * Copyright (c) 2003, 2013, 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
@@ -43,7 +43,7 @@
*
* @author Peter von der Ahé
* @author Joshua Bloch
- * @jls 9.6.1.4 Override
+ * @jls 9.6.1.4 @Override
* @since 1.5
*/
@Target(ElementType.METHOD)
--- old/src/share/classes/java/lang/SafeVarargs.java 2013-02-21
17:37:09.000000000 -0800
+++ new/src/share/classes/java/lang/SafeVarargs.java 2013-02-21
17:37:09.000000000 -0800
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2010, 2011, Oracle and/or its affiliates. All rights
reserved.
+ * Copyright (c) 2010, 2013, 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
@@ -85,6 +85,7 @@
* @since 1.7
* @jls 4.7 Reifiable Types
* @jls 8.4.1 Formal Parameters
+ * @jls 9.6.3.7 @SafeVarargs
*/
@Documented
@Retention(RetentionPolicy.RUNTIME)
--- old/src/share/classes/java/lang/SuppressWarnings.java 2013-02-21
17:37:10.000000000 -0800
+++ new/src/share/classes/java/lang/SuppressWarnings.java 2013-02-21
17:37:09.000000000 -0800
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2004, 2011, Oracle and/or its affiliates. All rights
reserved.
+ * Copyright (c) 2004, 2013, 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
@@ -41,8 +41,11 @@
* suppress a warning in a particular method, you should annotate that
* method rather than its class.
*
- * @since 1.5
* @author Josh Bloch
+ * @since 1.5
+ * @jls 5.1.9. Unchecked Conversion
+ * @jls 5.5.2. Checked Casts and Unchecked Casts
+ * @jls 9.6.3.5 @SuppressWarnings
*/
@Target({TYPE, FIELD, METHOD, PARAMETER, CONSTRUCTOR, LOCAL_VARIABLE})
@Retention(RetentionPolicy.SOURCE)
@@ -56,9 +59,11 @@
* free to emit a warning if an annotation contains an unrecognized
* warning name.
*
- * <p>Compiler vendors should document the warning names they
support in
- * conjunction with this annotation type. They are encouraged to
cooperate
- * to ensure that the same names work across multiple compilers.
+ * <p> The string {@code "unchecked"} is used to suppress
+ * unchecked warnings. Compiler vendors should document the
+ * additional warning names they support in conjunction with this
+ * annotation type. They are encouraged to cooperate to ensure
+ * that the same names work across multiple compilers.
*/
String[] value();
}
--- old/src/share/classes/java/lang/annotation/Inherited.java 2013-02-21
17:37:10.000000000 -0800
+++ new/src/share/classes/java/lang/annotation/Inherited.java 2013-02-21
17:37:10.000000000 -0800
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2003, 2004, Oracle and/or its affiliates. All rights
reserved.
+ * Copyright (c) 2003, 2013, 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
@@ -44,6 +44,7 @@
*
* @author Joshua Bloch
* @since 1.5
+ * @jls 9.6.3.3 @Inherited
*/
@Documented
@Retention(RetentionPolicy.RUNTIME)
--- old/src/share/classes/java/lang/annotation/Retention.java 2013-02-21
17:37:11.000000000 -0800
+++ new/src/share/classes/java/lang/annotation/Retention.java 2013-02-21
17:37:10.000000000 -0800
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2003, 2006, Oracle and/or its affiliates. All rights
reserved.
+ * Copyright (c) 2003, 2013, 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
@@ -38,6 +38,7 @@
*
* @author Joshua Bloch
* @since 1.5
+ * @jls 9.6.3.2 @Retention
*/
@Documented
@Retention(RetentionPolicy.RUNTIME)
--- old/src/share/classes/java/lang/annotation/Target.java 2013-02-21
17:37:11.000000000 -0800
+++ new/src/share/classes/java/lang/annotation/Target.java 2013-02-21
17:37:11.000000000 -0800
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2003, 2004, Oracle and/or its affiliates. All rights
reserved.
+ * Copyright (c) 2003, 2013, 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
@@ -59,6 +59,9 @@
* ...
* }
* </pre>
+ *
+ * @since 1.5
+ * @jls 9.6.3.1 @Target
*/
@Documented
@Retention(RetentionPolicy.RUNTIME)
More information about the core-libs-dev
mailing list