7015530: Reiterate API specializations in javax.lang.model.elment subinterfaces

Reviewed-by: jjg

langtools/src/share/classes/javax/lang/model/element/Element.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2006, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2011, 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
@@ -159,18 +159,26 @@ public interface Element {
     Set<Modifier> getModifiers();
 
     /**
-     * Returns the simple (unqualified) name of this element.
-     * The name of a generic type does not include any reference
-     * to its formal type parameters.
-     * For example, the simple name of the type element
-     * {@code java.util.Set<E>} is {@code "Set"}.
-     * If this element represents an unnamed package, an empty name is
-     * returned.  If it represents a constructor, the name "{@code
-     * <init>}" is returned.  If it represents a static initializer,
-     * the name "{@code <clinit>}" is returned.  If it represents an
-     * anonymous class or instance initializer, an empty name is
+     * Returns the simple (unqualified) name of this element.  The
+     * name of a generic type does not include any reference to its
+     * formal type parameters.
+     *
+     * For example, the simple name of the type element {@code
+     * java.util.Set<E>} is {@code "Set"}.
+     *
+     * If this element represents an unnamed {@linkplain
+     * PackageElement#getSimpleName package}, an empty name is
      * returned.
      *
+     * If it represents a {@linkplain ExecutableElement#getSimpleName
+     * constructor}, the name "{@code <init>}" is returned.  If it
+     * represents a {@linkplain ExecutableElement#getSimpleName static
+     * initializer}, the name "{@code <clinit>}" is returned.
+     *
+     * If it represents an {@linkplain TypeElement#getSimpleName
+     * anonymous class} or {@linkplain ExecutableElement#getSimpleName
+     * instance initializer}, an empty name is returned.
+     *
      * @return the simple name of this element
      */
     Name getSimpleName();
@@ -182,9 +190,18 @@ public interface Element {
      * <li> If this element is one whose declaration is lexically enclosed
      * immediately within the declaration of another element, that other
      * element is returned.
-     * <li> If this is a top-level type, its package is returned.
-     * <li> If this is a package, {@code null} is returned.
-     * <li> If this is a type parameter, {@code null} is returned.
+     *
+     * <li> If this is a {@linkplain TypeElement#getEnclosingElement
+     * top-level type}, its package is returned.
+     *
+     * <li> If this is a {@linkplain
+     * PackageElement#getEnclosingElement package}, {@code null} is
+     * returned.
+
+     * <li> If this is a {@linkplain
+     * TypeParameterElement#getEnclosingElement type parameter},
+     * {@code null} is returned.
+
      * </ul>
      *
      * @return the enclosing element, or {@code null} if there is none

langtools/src/share/classes/javax/lang/model/element/ExecutableElement.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2009, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2011, 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
@@ -97,4 +97,17 @@ public interface ExecutableElement extends Element, Parameterizable {
      * @return the default value, or {@code null} if none
      */
     AnnotationValue getDefaultValue();
+
+    /**
+     * Returns the simple name of a constructor, method, or
+     * initializer.  For a constructor, the name {@code "<init>"} is
+     * returned, for a static initializer, the name {@code "<clinit>"}
+     * is returned, and for an anonymous class or instance
+     * initializer, an empty name is returned.
+     *
+     * @return the simple name of a constructor, method, or
+     * initializer
+     */
+    @Override
+    Name getSimpleName();
 }

langtools/src/share/classes/javax/lang/model/element/PackageElement.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2009, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2011, 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
@@ -47,6 +47,16 @@ public interface PackageElement extends Element, QualifiedNameable {
      */
     Name getQualifiedName();
 
+    /**
+     * Returns the simple name of this package.  For an unnamed
+     * package, an empty name is returned
+     *
+     * @return the simple name of this package or an empty name if
+     * this is an unnamed package
+     */
+    @Override
+    Name getSimpleName();
+
     /**
      * Returns {@code true} is this is an unnamed package and {@code
      * false} otherwise.
@@ -56,4 +66,13 @@ public interface PackageElement extends Element, QualifiedNameable {
      * @jls3 7.4.2 Unnamed Packages
      */
     boolean isUnnamed();
+
+    /**
+     * Returns {@code null} since a package is not enclosed by another
+     * element.
+     *
+     * @return {@code null}
+     */
+    @Override
+    Element getEnclosingElement();
 }

langtools/src/share/classes/javax/lang/model/element/TypeElement.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2009, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2011, 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
@@ -105,6 +105,19 @@ public interface TypeElement extends Element, Parameterizable, QualifiedNameable
      */
     Name getQualifiedName();
 
+
+    /**
+     * Returns the simple name of this type element.
+     *
+     * For an anonymous class, an empty name is returned.
+     *
+     * @return the simple name of this class or interface,
+     * an empty name for an anonymous class
+     *
+     */
+    @Override
+    Name getSimpleName();
+
     /**
      * Returns the direct superclass of this type element.
      * If this type element represents an interface or the class
@@ -132,4 +145,16 @@ public interface TypeElement extends Element, Parameterizable, QualifiedNameable
      * if there are none
      */
     List<? extends TypeParameterElement> getTypeParameters();
+
+
+    /**
+     * Returns the package of a top-level type and returns the
+     * immediately lexically enclosing element for a {@linkplain
+     * NestingKind#isNested nested} type.
+     *
+     * @return the package of a top-level type, the immediately
+     * lexically enclosing element for a nested type
+     */
+    @Override
+    Element getEnclosingElement();
 }

langtools/src/share/classes/javax/lang/model/element/TypeParameterElement.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2006, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2011, 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,4 +62,12 @@ public interface TypeParameterElement extends Element {
      * there are none
      */
     List<? extends TypeMirror> getBounds();
+
+    /**
+     * Returns {@code null}.
+     *
+     * @return {@code null}
+     */
+    @Override
+    Element getEnclosingElement();
 }

langtools/src/share/classes/javax/lang/model/element/VariableElement.java

@@ -1,5 +1,5 @@
 /*
- * Copyright (c) 2005, 2006, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2011, 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
@@ -28,17 +28,16 @@ package javax.lang.model.element;
 import javax.lang.model.type.TypeMirror;
 import javax.lang.model.util.Elements;
 
-
 /**
  * Represents a field, {@code enum} constant, method or constructor
- * parameter, local variable, or exception parameter.
+ * parameter, local variable, resource variable, or exception
+ * parameter.
  *
  * @author Joseph D. Darcy
  * @author Scott Seligman
  * @author Peter von der Ahé
  * @since 1.6
  */
-
 public interface VariableElement extends Element {
 
     /**