JDK RFR of 6556996: (ann spec) SuppressWarnings strings should be documented

Remi Forax forax at univ-mlv.fr
Sat Feb 23 09:25:03 UTC 2013


On 02/22/2013 02:46 AM, Joe Darcy wrote:
> 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

Like the original submitter of the bug, I think that several other 
strings (at least rawtypes, varargs, deprecation, serial) should be 
documented with an explicit comment saying that they are not part of the 
specification.
Those flags are way too common to not be documented in the API.

Rémi

>
> --- 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