changeset 59964:0d3b9e32d012

8248428: Cleanup pass on javax.lang.model docs Reviewed-by: jjg
author darcy
date Fri, 26 Jun 2020 17:14:14 -0700
parents 3fa59689c0fe
children a95bc0e455e3
files src/java.compiler/share/classes/javax/annotation/processing/Filer.java src/java.compiler/share/classes/javax/annotation/processing/Processor.java src/java.compiler/share/classes/javax/lang/model/AnnotatedConstruct.java src/java.compiler/share/classes/javax/lang/model/UnknownEntityException.java src/java.compiler/share/classes/javax/lang/model/element/Element.java src/java.compiler/share/classes/javax/lang/model/element/RecordComponentElement.java src/java.compiler/share/classes/javax/lang/model/element/package-info.java src/java.compiler/share/classes/javax/lang/model/type/NullType.java src/java.compiler/share/classes/javax/lang/model/type/PrimitiveType.java src/java.compiler/share/classes/javax/lang/model/type/ReferenceType.java src/java.compiler/share/classes/javax/lang/model/type/TypeMirror.java src/java.compiler/share/classes/javax/lang/model/type/TypeVariable.java src/java.compiler/share/classes/javax/lang/model/type/UnionType.java src/java.compiler/share/classes/javax/lang/model/type/WildcardType.java src/java.compiler/share/classes/javax/lang/model/type/package-info.java
diffstat 15 files changed, 72 insertions(+), 41 deletions(-) [+]
line wrap: on
line diff
--- a/src/java.compiler/share/classes/javax/annotation/processing/Filer.java	Fri Jun 26 19:26:30 2020 +0000
+++ b/src/java.compiler/share/classes/javax/annotation/processing/Filer.java	Fri Jun 26 17:14:14 2020 -0700
@@ -164,7 +164,7 @@
      * An implementation may use information about the configuration of
      * the annotation processing tool as part of the inference.
      *
-     * <p>Creating a source file in or for an unnamed package in a named
+     * <p>Creating a source file in or for an <em>unnamed</em> package in a <em>named</em>
      * module is <em>not</em> supported.
      *
      * @apiNote To use a particular {@linkplain
@@ -240,7 +240,7 @@
      * An implementation may use information about the configuration of
      * the annotation processing tool as part of the inference.
      *
-     * <p>Creating a class file in or for an unnamed package in a named
+     * <p>Creating a class file in or for an <em>unnamed</em> package in a <em>named</em>
      * module is <em>not</em> supported.
      *
      * @apiNote To avoid subsequent errors, the contents of the class
--- a/src/java.compiler/share/classes/javax/annotation/processing/Processor.java	Fri Jun 26 19:26:30 2020 +0000
+++ b/src/java.compiler/share/classes/javax/annotation/processing/Processor.java	Fri Jun 26 17:14:14 2020 -0700
@@ -234,7 +234,7 @@
      * in which case it may wish to report a warning.
      *
      * @return the options recognized by this processor or an
-     *         empty collection if none
+     *         empty set if none
      * @see javax.annotation.processing.SupportedOptions
      */
     Set<String> getSupportedOptions();
@@ -286,7 +286,8 @@
      * </blockquote>
      *
      * where <i>TypeName</i> and <i>ModuleName</i> are as defined in
-     * <cite>The Java&trade; Language Specification</cite>.
+     * <cite>The Java&trade; Language Specification</cite>
+     * ({@jls 6.5 Determining the Meaning of a Name}).
      *
      * @apiNote When running in an environment which supports modules,
      * processors are encouraged to include the module prefix when
@@ -297,9 +298,9 @@
      * environment without modules.
      *
      * @return the names of the annotation types supported by this processor
+     *          or an empty set if none
      * @see javax.annotation.processing.SupportedAnnotationTypes
      * @jls 3.8 Identifiers
-     * @jls 6.5 Determining the Meaning of a Name
      */
     Set<String> getSupportedAnnotationTypes();
 
@@ -390,14 +391,14 @@
     * <pre>
     * import static javax.annotation.processing.Completions.*;
     * ...
-    * return Arrays.asList({@link Completions#of(String) of}(&quot;3&quot;),
-    *                      of(&quot;7&quot;),
-    *                      of(&quot;31&quot;),
-    *                      of(&quot;127&quot;),
-    *                      of(&quot;8191&quot;),
-    *                      of(&quot;131071&quot;),
-    *                      of(&quot;524287&quot;),
-    *                      of(&quot;2147483647&quot;));
+    * return List.of({@link Completions#of(String) of}(&quot;3&quot;),
+    *                of(&quot;7&quot;),
+    *                of(&quot;31&quot;),
+    *                of(&quot;127&quot;),
+    *                of(&quot;8191&quot;),
+    *                of(&quot;131071&quot;),
+    *                of(&quot;524287&quot;),
+    *                of(&quot;2147483647&quot;));
     * </pre>
     * </blockquote>
     *
@@ -406,14 +407,14 @@
     *
     * <blockquote>
     * <pre>
-    * return Arrays.asList({@link Completions#of(String, String) of}(&quot;3&quot;,          &quot;M2&quot;),
-    *                      of(&quot;7&quot;,          &quot;M3&quot;),
-    *                      of(&quot;31&quot;,         &quot;M5&quot;),
-    *                      of(&quot;127&quot;,        &quot;M7&quot;),
-    *                      of(&quot;8191&quot;,       &quot;M13&quot;),
-    *                      of(&quot;131071&quot;,     &quot;M17&quot;),
-    *                      of(&quot;524287&quot;,     &quot;M19&quot;),
-    *                      of(&quot;2147483647&quot;, &quot;M31&quot;));
+    * return List.of({@link Completions#of(String, String) of}(&quot;3&quot;,          &quot;M2&quot;),
+    *                of(&quot;7&quot;,          &quot;M3&quot;),
+    *                of(&quot;31&quot;,         &quot;M5&quot;),
+    *                of(&quot;127&quot;,        &quot;M7&quot;),
+    *                of(&quot;8191&quot;,       &quot;M13&quot;),
+    *                of(&quot;131071&quot;,     &quot;M17&quot;),
+    *                of(&quot;524287&quot;,     &quot;M19&quot;),
+    *                of(&quot;2147483647&quot;, &quot;M31&quot;));
     * </pre>
     * </blockquote>
     *
--- a/src/java.compiler/share/classes/javax/lang/model/AnnotatedConstruct.java	Fri Jun 26 19:26:30 2020 +0000
+++ b/src/java.compiler/share/classes/javax/lang/model/AnnotatedConstruct.java	Fri Jun 26 17:14:14 2020 -0700
@@ -81,8 +81,8 @@
  * <i>C</i>, then if <i>AT</i> is repeatable annotation type, an
  * annotation of type <i>ATC</i> is {@linkplain javax.lang.model.util.Elements#getOrigin(AnnotatedConstruct, AnnotationMirror) implicitly declared} on <i>C</i>.
  * <li> A representation of <i>A</i> appears in the executable output
- * for <i>C</i>, such as the {@code RuntimeVisibleAnnotations} or
- * {@code RuntimeVisibleParameterAnnotations} attributes of a class
+ * for <i>C</i>, such as the {@code RuntimeVisibleAnnotations} (JVMS {@jvms 4.7.16}) or
+ * {@code RuntimeVisibleParameterAnnotations} (JVMS {@jvms 4.7.17}) attributes of a class
  * file.
  *
  * </ul>
--- a/src/java.compiler/share/classes/javax/lang/model/UnknownEntityException.java	Fri Jun 26 19:26:30 2020 +0000
+++ b/src/java.compiler/share/classes/javax/lang/model/UnknownEntityException.java	Fri Jun 26 17:14:14 2020 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009, 2017, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2009, 2020, 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
@@ -32,10 +32,6 @@
  * this exception may be thrown by visitors to indicate that the
  * visitor was created for a prior version of the language.
  *
- * @apiNote A common superclass for exceptions specific to different
- * kinds of unknown entities allows a single catch block to easily
- * provide uniform handling of those related conditions.
- *
  * @author Joseph D. Darcy
  * @see javax.lang.model.element.UnknownElementException
  * @see javax.lang.model.element.UnknownAnnotationValueException
--- a/src/java.compiler/share/classes/javax/lang/model/element/Element.java	Fri Jun 26 19:26:30 2020 +0000
+++ b/src/java.compiler/share/classes/javax/lang/model/element/Element.java	Fri Jun 26 17:14:14 2020 -0700
@@ -37,7 +37,7 @@
 
 /**
  * Represents a program element such as a module, package, class, or method.
- * Each element represents a static, language-level construct
+ * Each element represents a compile-time language-level construct
  * (and not, for example, a runtime construct of the virtual machine).
  *
  * <p> Elements should be compared using the {@link #equals(Object)}
--- a/src/java.compiler/share/classes/javax/lang/model/element/RecordComponentElement.java	Fri Jun 26 19:26:30 2020 +0000
+++ b/src/java.compiler/share/classes/javax/lang/model/element/RecordComponentElement.java	Fri Jun 26 17:14:14 2020 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2019, 2020, 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
@@ -55,7 +55,7 @@
      * Returns the simple name of this record component.
      *
      * <p>The name of each record component must be distinct from the
-     * names of all other record components.
+     * names of all other record components of the same record.
      *
      * @return the simple name of this record component
      *
--- a/src/java.compiler/share/classes/javax/lang/model/element/package-info.java	Fri Jun 26 19:26:30 2020 +0000
+++ b/src/java.compiler/share/classes/javax/lang/model/element/package-info.java	Fri Jun 26 17:14:14 2020 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2020, 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
@@ -50,7 +50,7 @@
  * recovered from class files and class files might not be able to
  * provide source position information.
  *
- * Names of parameters may not be recoverable from class files.
+ * Names of {@linkplain javax.lang.model.element.ExecutableElement#getParameters() parameters} may not be recoverable from class files.
  *
  * The {@linkplain javax.lang.model.element.Modifier modifiers} on an
  * element created from a class file may differ in some cases from an
@@ -108,6 +108,15 @@
  * @author Scott Seligman
  * @author Peter von der Ah&eacute;
  * @see javax.lang.model.util.Elements
+ * @jls 6.1 Declarations
+ * @jls 7.4 Package Declarations
+ * @jls 7.7 Module Declarations
+ * @jls 8.1 Class Declarations
+ * @jls 8.3 Field Declarations
+ * @jls 8.4 Method Declarations
+ * @jls 8.5 Member Type Declarations
+ * @jls 8.8 Constructor Declarations
+ * @jls 9.1 Interface Declarations
  * @since 1.6
  */
 package javax.lang.model.element;
--- a/src/java.compiler/share/classes/javax/lang/model/type/NullType.java	Fri Jun 26 19:26:30 2020 +0000
+++ b/src/java.compiler/share/classes/javax/lang/model/type/NullType.java	Fri Jun 26 17:14:14 2020 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2006, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2020, 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
@@ -33,6 +33,8 @@
  * @author Joseph D. Darcy
  * @author Scott Seligman
  * @author Peter von der Ah&eacute;
+ * @jls 3.10.7 The Null Literal
+ * @jls 4.1 The Kinds of Types and Values
  * @since 1.6
  */
 
--- a/src/java.compiler/share/classes/javax/lang/model/type/PrimitiveType.java	Fri Jun 26 19:26:30 2020 +0000
+++ b/src/java.compiler/share/classes/javax/lang/model/type/PrimitiveType.java	Fri Jun 26 17:14:14 2020 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2006, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2020, 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,6 +34,7 @@
  * @author Joseph D. Darcy
  * @author Scott Seligman
  * @author Peter von der Ah&eacute;
+ * @jls 4.2 Primitive Types and Values
  * @since 1.6
  */
 public interface PrimitiveType extends TypeMirror {
--- a/src/java.compiler/share/classes/javax/lang/model/type/ReferenceType.java	Fri Jun 26 19:26:30 2020 +0000
+++ b/src/java.compiler/share/classes/javax/lang/model/type/ReferenceType.java	Fri Jun 26 17:14:14 2020 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2006, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2020, 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,6 +34,7 @@
  * @author Joseph D. Darcy
  * @author Scott Seligman
  * @author Peter von der Ah&eacute;
+ * @jls 4.3 Reference Types and Values
  * @since 1.6
  */
 public interface ReferenceType extends TypeMirror {
--- a/src/java.compiler/share/classes/javax/lang/model/type/TypeMirror.java	Fri Jun 26 19:26:30 2020 +0000
+++ b/src/java.compiler/share/classes/javax/lang/model/type/TypeMirror.java	Fri Jun 26 17:14:14 2020 -0700
@@ -55,6 +55,14 @@
  * @author Peter von der Ah&eacute;
  * @see Element
  * @see Types
+ * @jls 4.1 The Kinds of Types and Values
+ * @jls 4.2 Primitive Types and Values
+ * @jls 4.3 Reference Types and Values
+ * @jls 4.4 Type Variables
+ * @jls 4.5 Parameterized Types
+ * @jls 4.8 Raw Types
+ * @jls 4.9 Intersection Types
+ * @jls 10.1 Array Types
  * @since 1.6
  */
 public interface TypeMirror extends javax.lang.model.AnnotatedConstruct {
--- a/src/java.compiler/share/classes/javax/lang/model/type/TypeVariable.java	Fri Jun 26 19:26:30 2020 +0000
+++ b/src/java.compiler/share/classes/javax/lang/model/type/TypeVariable.java	Fri Jun 26 17:14:14 2020 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2020, 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,13 +38,14 @@
  * type, method, or constructor.
  * A type variable may also be declared implicitly, as by
  * the capture conversion of a wildcard type argument
- * (see chapter 5 of
+ * (see chapter {@jls 5} of
  * <cite>The Java&trade; Language Specification</cite>).
  *
  * @author Joseph D. Darcy
  * @author Scott Seligman
  * @author Peter von der Ah&eacute;
  * @see TypeParameterElement
+ * @jls 4.4 Type Variables
  * @since 1.6
  */
 public interface TypeVariable extends ReferenceType {
@@ -67,6 +68,7 @@
      * {@linkplain IntersectionType#getBounds() bounds}.
      *
      * @return the upper bound of this type variable
+     * @jls 4.9 Intersection Types
      */
     TypeMirror getUpperBound();
 
@@ -78,6 +80,7 @@
      * lower bound of {@link NullType}.
      *
      * @return the lower bound of this type variable
+     * @jls 18.1.3. Bounds
      */
     TypeMirror getLowerBound();
 }
--- a/src/java.compiler/share/classes/javax/lang/model/type/UnionType.java	Fri Jun 26 19:26:30 2020 +0000
+++ b/src/java.compiler/share/classes/javax/lang/model/type/UnionType.java	Fri Jun 26 17:14:14 2020 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2010, 2017, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2010, 2020, 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
@@ -33,6 +33,7 @@
  * Union types can appear as the type of a multi-catch exception
  * parameter.
  *
+ * @jls 14.20 The try statement
  * @since 1.7
  */
 public interface UnionType extends TypeMirror {
--- a/src/java.compiler/share/classes/javax/lang/model/type/WildcardType.java	Fri Jun 26 19:26:30 2020 +0000
+++ b/src/java.compiler/share/classes/javax/lang/model/type/WildcardType.java	Fri Jun 26 17:14:14 2020 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2006, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2020, 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,6 +41,7 @@
  * @author Joseph D. Darcy
  * @author Scott Seligman
  * @author Peter von der Ah&eacute;
+ * @jls 4.5.1 Type Arguments of Parameterized Types
  * @since 1.6
  */
 public interface WildcardType extends TypeMirror {
--- a/src/java.compiler/share/classes/javax/lang/model/type/package-info.java	Fri Jun 26 19:26:30 2020 +0000
+++ b/src/java.compiler/share/classes/javax/lang/model/type/package-info.java	Fri Jun 26 17:14:14 2020 -0700
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2020, 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
@@ -37,6 +37,14 @@
  * @author Scott Seligman
  * @author Peter von der Ah&eacute;
  * @see javax.lang.model.util.Types
+ * @jls 4.1 The Kinds of Types and Values
+ * @jls 4.2 Primitive Types and Values
+ * @jls 4.3 Reference Types and Values
+ * @jls 4.4 Type Variables
+ * @jls 4.5 Parameterized Types
+ * @jls 4.8 Raw Types
+ * @jls 4.9 Intersection Types
+ * @jls 10.1 Array Types
  * @since 1.6
  */
 package javax.lang.model.type;