6556996: (ann spec) SuppressWarnings strings should be documented

Reviewed-by: mduigou, chegar, abuckley

src/share/classes/java/lang/Deprecated.java

 /*
- * 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 @@ import static java.lang.annotation.ElementType.*;
  *
  * @author  Neal Gafter
  * @since 1.5
+ * @jls 9.6.3.6 @Deprecated
  */
 @Documented
 @Retention(RetentionPolicy.RUNTIME)

src/share/classes/java/lang/Override.java

 /*
- * 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 @@ import java.lang.annotation.*;
  *
  * @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)

src/share/classes/java/lang/SafeVarargs.java

 /*
- * 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 @@ import java.lang.annotation.*;
  * @since 1.7
  * @jls 4.7 Reifiable Types
  * @jls 8.4.1 Formal Parameters
+ * @jls 9.6.3.7 @SafeVarargs
  */
 @Documented
 @Retention(RetentionPolicy.RUNTIME)

src/share/classes/java/lang/SuppressWarnings.java

 /*
- * 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,13 @@ import static java.lang.annotation.ElementType.*;
  * 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 4.8 Raw Types
+ * @jls 4.12.2 Variables of Reference Type
+ * @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 +61,11 @@ public @interface SuppressWarnings {
      * 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();
 }

src/share/classes/java/lang/annotation/Inherited.java

 /*
- * 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 @@ package java.lang.annotation;
  *
  * @author  Joshua Bloch
  * @since 1.5
+ * @jls 9.6.3.3 @Inherited
  */
 @Documented
 @Retention(RetentionPolicy.RUNTIME)

src/share/classes/java/lang/annotation/Retention.java

 /*
- * 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 @@ package java.lang.annotation;
  *
  * @author  Joshua Bloch
  * @since 1.5
+ * @jls 9.6.3.2 @Retention
  */
 @Documented
 @Retention(RetentionPolicy.RUNTIME)

src/share/classes/java/lang/annotation/Target.java

 /*
- * 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 @@ package java.lang.annotation;
  *        ...
  *    }
  * </pre>
+ *
+ * @since 1.5
+ * @jls 9.6.3.1 @Target
  */
 @Documented
 @Retention(RetentionPolicy.RUNTIME)