changeset 3933:ec4be8a26914

8173676: Improvements to javax.annotation.processing and javax.lang.model doc Reviewed-by: anazarov
author darcy
date Wed, 01 Feb 2017 11:25:56 -0800
parents ca18223ce9ee
children 3163200b0279
files src/java.compiler/share/classes/javax/annotation/processing/Filer.java src/java.compiler/share/classes/javax/annotation/processing/FilerException.java src/java.compiler/share/classes/javax/annotation/processing/Processor.java src/java.compiler/share/classes/javax/annotation/processing/RoundEnvironment.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/ModuleElement.java src/java.compiler/share/classes/javax/lang/model/element/NestingKind.java src/java.compiler/share/classes/javax/lang/model/element/PackageElement.java src/java.compiler/share/classes/javax/lang/model/element/Parameterizable.java src/java.compiler/share/classes/javax/lang/model/element/TypeElement.java src/java.compiler/share/classes/javax/lang/model/element/UnknownAnnotationValueException.java src/java.compiler/share/classes/javax/lang/model/element/UnknownElementException.java src/java.compiler/share/classes/javax/lang/model/element/package-info.java src/java.compiler/share/classes/javax/lang/model/type/IntersectionType.java src/java.compiler/share/classes/javax/lang/model/type/UnionType.java src/java.compiler/share/classes/javax/lang/model/type/UnknownTypeException.java src/java.compiler/share/classes/javax/lang/model/util/ElementFilter.java src/java.compiler/share/classes/javax/lang/model/util/Elements.java
diffstat 20 files changed, 67 insertions(+), 72 deletions(-) [+]
line wrap: on
line diff
--- a/src/java.compiler/share/classes/javax/annotation/processing/Filer.java	Wed Feb 01 09:10:07 2017 -0800
+++ b/src/java.compiler/share/classes/javax/annotation/processing/Filer.java	Wed Feb 01 11:25:56 2017 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2017, 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
@@ -264,7 +264,7 @@
      * @param moduleAndPkg module and/or package relative to which the file
      *           should be named, or the empty string if none
      * @param relativeName final pathname components of the file
-     * @param originatingElements type or package elements causally
+     * @param originatingElements type or package or module elements causally
      * associated with the creation of this file, may be elided or
      * {@code null}
      * @return a {@code FileObject} to write the new resource
--- a/src/java.compiler/share/classes/javax/annotation/processing/FilerException.java	Wed Feb 01 09:10:07 2017 -0800
+++ b/src/java.compiler/share/classes/javax/annotation/processing/FilerException.java	Wed Feb 01 11:25:56 2017 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2012, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2017, 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
@@ -31,7 +31,7 @@
  * Indicates a {@link Filer} detected an attempt to open a file that
  * would violate the guarantees provided by the {@code Filer}.  Those
  * guarantees include not creating the same file more than once, not
- * creating multiple files corresponding to the same type, and not
+ * creating multiple files corresponding to the same type or package, and not
  * creating files for types with invalid names.
  *
  * @author Joseph D. Darcy
--- a/src/java.compiler/share/classes/javax/annotation/processing/Processor.java	Wed Feb 01 09:10:07 2017 -0800
+++ b/src/java.compiler/share/classes/javax/annotation/processing/Processor.java	Wed Feb 01 11:25:56 2017 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2017, 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
@@ -194,7 +194,7 @@
  * <p>The {@link Filer} interface discusses restrictions on how
  * processors can operate on files.
  *
- * <p>Note that implementors of this interface may find it convenient
+ * @apiNote Implementors of this interface may find it convenient
  * to extend {@link AbstractProcessor} rather than implementing this
  * interface directly.
  *
@@ -315,7 +315,7 @@
      * is returned, the annotation types are unclaimed and subsequent
      * processors may be asked to process them.  A processor may
      * always return the same boolean value or may vary the result
-     * based on chosen criteria.
+     * based on its own chosen criteria.
      *
      * <p>The input set will be empty if the processor supports {@code
      * "*"} and the root elements have no annotations.  A {@code
@@ -343,8 +343,8 @@
     * <p>Since incomplete programs are being modeled, some of the
     * parameters may only have partial information or may be {@code
     * null}.  At least one of {@code element} and {@code userText}
-    * must be non-{@code null}.  If {@code element} is non-{@code
-    * null}, {@code annotation} and {@code member} may be {@code
+    * must be non-{@code null}.  If {@code element} is non-{@code null},
+    * {@code annotation} and {@code member} may be {@code
     * null}.  Processors may not throw a {@code NullPointerException}
     * if some parameters are {@code null}; if a processor has no
     * completions to offer based on the provided information, an
--- a/src/java.compiler/share/classes/javax/annotation/processing/RoundEnvironment.java	Wed Feb 01 09:10:07 2017 -0800
+++ b/src/java.compiler/share/classes/javax/annotation/processing/RoundEnvironment.java	Wed Feb 01 11:25:56 2017 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2017, 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
@@ -65,7 +65,7 @@
     boolean errorRaised();
 
     /**
-     * Returns the root elements for annotation processing generated
+     * Returns the {@linkplain Processor root elements} for annotation processing generated
      * by the prior round.
      *
      * @return the root elements for annotation processing generated
--- a/src/java.compiler/share/classes/javax/lang/model/AnnotatedConstruct.java	Wed Feb 01 09:10:07 2017 -0800
+++ b/src/java.compiler/share/classes/javax/lang/model/AnnotatedConstruct.java	Wed Feb 01 11:25:56 2017 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2013, 2017, 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
@@ -62,7 +62,7 @@
  *
  * If there are multiple annotations of type <i>AT</i> present on
  * <i>C</i>, then if <i>AT</i> is repeatable annotation type, an
- * annotation of type <i>ATC</i> is implicitly declared on <i>C</i>.
+ * 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
--- a/src/java.compiler/share/classes/javax/lang/model/UnknownEntityException.java	Wed Feb 01 09:10:07 2017 -0800
+++ b/src/java.compiler/share/classes/javax/lang/model/UnknownEntityException.java	Wed Feb 01 11:25:56 2017 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2009, 2017, 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,8 +32,9 @@
  * this exception may be thrown by visitors to indicate that the
  * visitor was created for a prior version of the language.
  *
- * <p>A common superclass for those exceptions allows a single catch
- * block to have code handling them uniformly.
+ * @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
--- a/src/java.compiler/share/classes/javax/lang/model/element/Element.java	Wed Feb 01 09:10:07 2017 -0800
+++ b/src/java.compiler/share/classes/javax/lang/model/element/Element.java	Wed Feb 01 11:25:56 2017 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2017, 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,7 +37,7 @@
 
 
 /**
- * Represents a program element such as a package, class, or method.
+ * Represents a program element such as a module, package, class, or method.
  * Each element represents a static, language-level construct
  * (and not, for example, a runtime construct of the virtual machine).
  *
@@ -180,7 +180,7 @@
      * any elements; however, that may change as this API or the
      * programming language evolves.
      *
-     * <p>Note that elements of certain kinds can be isolated using
+     * @apiNote Elements of certain kinds can be isolated using
      * methods in {@link ElementFilter}.
      *
      * @return the enclosed elements, or an empty list if none
@@ -197,7 +197,7 @@
      * Returns {@code true} if the argument represents the same
      * element as {@code this}, or {@code false} otherwise.
      *
-     * <p>Note that the identity of an element involves implicit state
+     * @apiNote The identity of an element involves implicit state
      * not directly accessible from the element's methods, including
      * state about the presence of unrelated types.  Element objects
      * created by different implementations of these interfaces should
--- a/src/java.compiler/share/classes/javax/lang/model/element/ModuleElement.java	Wed Feb 01 09:10:07 2017 -0800
+++ b/src/java.compiler/share/classes/javax/lang/model/element/ModuleElement.java	Wed Feb 01 11:25:56 2017 -0800
@@ -37,17 +37,18 @@
 public interface ModuleElement extends Element, QualifiedNameable {
 
     /**
-     * Returns the fully qualified name of this module.
+     * Returns the fully qualified name of this module.  For an
+     * {@linkplain #isUnnamed() unnamed module}, an empty name is returned.
      *
-     * @return the qualified name of this module, or an
+     * @return the fully qualified name of this module, or an
      * empty name if this is an unnamed module
      */
     @Override
     Name getQualifiedName();
 
     /**
-     * Returns the simple name of this module.  For an unnamed
-     * module, an empty name is returned.
+     * Returns the simple name of this module.  For an {@linkplain
+     * #isUnnamed() unnamed module}, an empty name is returned.
      *
      * @return the simple name of this module or an empty name if
      * this is an unnamed module
--- a/src/java.compiler/share/classes/javax/lang/model/element/NestingKind.java	Wed Feb 01 09:10:07 2017 -0800
+++ b/src/java.compiler/share/classes/javax/lang/model/element/NestingKind.java	Wed Feb 01 11:25:56 2017 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2017, 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
@@ -89,25 +89,29 @@
 
     /**
      * A type that is a named member of another type.
+     * @jls 8.5 Member Type Declarations
      */
     MEMBER,
 
     /**
      * A named type declared within a construct other than a type.
+     * @jls 14.3 Local Class Declarations
      */
     LOCAL,
 
     /**
      * A type without a name.
+     * @jls 15.9.5 Anonymous Class Declarations
      */
     ANONYMOUS;
 
     /**
      * Does this constant correspond to a nested type element?
      * A <i>nested</i> type element is any that is not top-level.
-     * An <i>inner</i> type element is any nested type element that
+     * More specifically, an <i>inner</i> type element is any nested type element that
      * is not {@linkplain Modifier#STATIC static}.
      * @return whether or not the constant is nested
+     * @jls 14.3 Inner Classes and Enclosing Instances
      */
     public boolean isNested() {
         return this != TOP_LEVEL;
--- a/src/java.compiler/share/classes/javax/lang/model/element/PackageElement.java	Wed Feb 01 09:10:07 2017 -0800
+++ b/src/java.compiler/share/classes/javax/lang/model/element/PackageElement.java	Wed Feb 01 11:25:56 2017 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2015, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2017, 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
@@ -42,6 +42,7 @@
     /**
      * Returns the fully qualified name of this package.
      * This is also known as the package's <i>canonical</i> name.
+     * For an {@linkplain #isUnnamed() unnamed package}, an empty name is returned.
      *
      * @return the fully qualified name of this package, or an
      * empty name if this is an unnamed package
@@ -50,8 +51,8 @@
     Name getQualifiedName();
 
     /**
-     * Returns the simple name of this package.  For an unnamed
-     * package, an empty name is returned.
+     * Returns the simple name of this package.  For an {@linkplain
+     * #isUnnamed() unnamed package}, an empty name is returned.
      *
      * @return the simple name of this package or an empty name if
      * this is an unnamed package
--- a/src/java.compiler/share/classes/javax/lang/model/element/Parameterizable.java	Wed Feb 01 09:10:07 2017 -0800
+++ b/src/java.compiler/share/classes/javax/lang/model/element/Parameterizable.java	Wed Feb 01 11:25:56 2017 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2009, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2009, 2017, 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
@@ -35,7 +35,7 @@
  */
 public interface Parameterizable extends Element {
     /**
-     * Returns the formal type parameters of the type element in
+     * Returns the formal type parameters of an element in
      * declaration order.
      *
      * @return the formal type parameters, or an empty list
--- a/src/java.compiler/share/classes/javax/lang/model/element/TypeElement.java	Wed Feb 01 09:10:07 2017 -0800
+++ b/src/java.compiler/share/classes/javax/lang/model/element/TypeElement.java	Wed Feb 01 11:25:56 2017 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2017, 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
@@ -67,14 +67,14 @@
      * the implicit {@code values} and {@code valueOf} methods of an
      * enum type.
      *
-     * <p> Note that as a particular instance of the {@linkplain
+     * @apiNote As a particular instance of the {@linkplain
      * javax.lang.model.element general accuracy requirements} and the
      * ordering behavior required of this interface, the list of
      * enclosed elements will be returned in the natural order for the
      * originating source of information about the type.  For example,
      * if the information about the type is originating from a source
      * file, the elements will be returned in source code order.
-     * (However, in that case the the ordering of synthesized
+     * (However, in that case the the ordering of {@linkplain Elements.Origin#MANDATED mandated}
      * elements, such as a default constructor, is not specified.)
      *
      * @return the enclosed elements in proper order, or an empty list if none
--- a/src/java.compiler/share/classes/javax/lang/model/element/UnknownAnnotationValueException.java	Wed Feb 01 09:10:07 2017 -0800
+++ b/src/java.compiler/share/classes/javax/lang/model/element/UnknownAnnotationValueException.java	Wed Feb 01 11:25:56 2017 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2009, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2017, 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
@@ -79,7 +79,7 @@
     /**
      * Returns the additional argument.
      *
-     * @return the additional argument
+     * @return the additional argument, or {@code null} if unavailable
      */
     public Object getArgument() {
         return parameter;
--- a/src/java.compiler/share/classes/javax/lang/model/element/UnknownElementException.java	Wed Feb 01 09:10:07 2017 -0800
+++ b/src/java.compiler/share/classes/javax/lang/model/element/UnknownElementException.java	Wed Feb 01 11:25:56 2017 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2009, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2017, 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
@@ -77,7 +77,7 @@
     /**
      * Returns the additional argument.
      *
-     * @return the additional argument
+     * @return the additional argument, or {@code null} if unavailable
      */
     public Object getArgument() {
         return parameter;
--- a/src/java.compiler/share/classes/javax/lang/model/element/package-info.java	Wed Feb 01 09:10:07 2017 -0800
+++ b/src/java.compiler/share/classes/javax/lang/model/element/package-info.java	Wed Feb 01 11:25:56 2017 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2017, 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
@@ -87,14 +87,14 @@
  * If a program is syntactically valid but erroneous in some other
  * fashion, any returned model must have no less information than if
  * all the method bodies in the program were replaced by {@code "throw
- * new RuntimeException();"}.  If a program refers to a missing type XYZ,
+ * new RuntimeException();"}.  If a program refers to a missing type Xyz,
  * the returned model must contain no less information than if the
- * declaration of type XYZ were assumed to be {@code "class XYZ {}"},
- * {@code "interface XYZ {}"}, {@code "enum XYZ {}"}, or {@code
- * "@interface XYZ {}"}. If a program refers to a missing type {@code
- * XYZ<K1, ... ,Kn>}, the returned model must contain no less
- * information than if the declaration of XYZ were assumed to be
- * {@code "class XYZ<T1, ... ,Tn> {}"} or {@code "interface XYZ<T1,
+ * declaration of type Xyz were assumed to be {@code "class Xyz {}"},
+ * {@code "interface Xyz {}"}, {@code "enum Xyz {}"}, or {@code
+ * "@interface Xyz {}"}. If a program refers to a missing type {@code
+ * Xyz<K1, ... ,Kn>}, the returned model must contain no less
+ * information than if the declaration of Xyz were assumed to be
+ * {@code "class Xyz<T1, ... ,Tn> {}"} or {@code "interface Xyz<T1,
  * ... ,Tn> {}"}
  *
  * <p> Unless otherwise specified in a particular implementation, the
--- a/src/java.compiler/share/classes/javax/lang/model/type/IntersectionType.java	Wed Feb 01 09:10:07 2017 -0800
+++ b/src/java.compiler/share/classes/javax/lang/model/type/IntersectionType.java	Wed Feb 01 11:25:56 2017 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2012, 2013, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2012, 2017, 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,14 +33,12 @@
  * <p>An intersection type can be either implicitly or explicitly
  * declared in a program. For example, the bound of the type parameter
  * {@code <T extends Number & Runnable>} is an (implicit) intersection
- * type.  As of {@link javax.lang.model.SourceVersion#RELEASE_8
- * RELEASE_8}, this is represented by an {@code IntersectionType} with
+ * type.  This is represented by an {@code IntersectionType} with
  * {@code Number} and {@code Runnable} as its bounds.
  *
- * @implNote Also as of {@link
- * javax.lang.model.SourceVersion#RELEASE_8 RELEASE_8}, in the
- * reference implementation an {@code IntersectionType} is used to
- * model the explicit target type of a cast expression.
+ * @implNote In the reference implementation an {@code
+ * IntersectionType} is used to model the explicit target type of a
+ * cast expression.
  *
  * @since 1.8
  */
@@ -49,7 +47,7 @@
     /**
      * Return the bounds comprising this intersection type.
      *
-     * @return the bounds of this intersection types.
+     * @return the bounds of this intersection type
      */
     List<? extends TypeMirror> getBounds();
 }
--- a/src/java.compiler/share/classes/javax/lang/model/type/UnionType.java	Wed Feb 01 09:10:07 2017 -0800
+++ b/src/java.compiler/share/classes/javax/lang/model/type/UnionType.java	Wed Feb 01 11:25:56 2017 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2010, 2011, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2010, 2017, 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
@@ -30,9 +30,8 @@
 /**
  * Represents a union type.
  *
- * As of the {@link javax.lang.model.SourceVersion#RELEASE_7
- * RELEASE_7} source version, union types can appear as the type
- * of a multi-catch exception parameter.
+ * Union types can appear as the type of a multi-catch exception
+ * parameter.
  *
  * @since 1.7
  */
--- a/src/java.compiler/share/classes/javax/lang/model/type/UnknownTypeException.java	Wed Feb 01 09:10:07 2017 -0800
+++ b/src/java.compiler/share/classes/javax/lang/model/type/UnknownTypeException.java	Wed Feb 01 11:25:56 2017 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2009, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2017, 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
@@ -77,7 +77,7 @@
     /**
      * Returns the additional argument.
      *
-     * @return the additional argument
+     * @return the additional argument, or {@code null} if unavailable
      */
     public Object getArgument() {
         return parameter;
--- a/src/java.compiler/share/classes/javax/lang/model/util/ElementFilter.java	Wed Feb 01 09:10:07 2017 -0800
+++ b/src/java.compiler/share/classes/javax/lang/model/util/ElementFilter.java	Wed Feb 01 11:25:56 2017 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2017, 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,15 +55,6 @@
  * arguments to methods in this class, a {@code NullPointerException}
  * will be thrown.
  *
- * <p>Note that a <i>static import</i> statement can make the text of
- * calls to the methods in this class more concise; for example:
- *
- * <blockquote><pre>
- *     import static javax.lang.model.util.ElementFilter.*;
- *     ...
- *         {@code List<VariableElement>} fs = fieldsIn(someClass.getEnclosedElements());
- * </pre></blockquote>
- *
  * @author Joseph D. Darcy
  * @author Scott Seligman
  * @author Peter von der Ah&eacute;
--- a/src/java.compiler/share/classes/javax/lang/model/util/Elements.java	Wed Feb 01 09:10:07 2017 -0800
+++ b/src/java.compiler/share/classes/javax/lang/model/util/Elements.java	Wed Feb 01 11:25:56 2017 -0800
@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2016, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2017, 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
@@ -348,7 +348,7 @@
      * declared directly.  For a class the result also includes its
      * constructors, but not local or anonymous classes.
      *
-     * <p>Note that elements of certain kinds can be isolated using
+     * @apiNote Elements of certain kinds can be isolated using
      * methods in {@link ElementFilter}.
      *
      * @param type  the type being examined