7130768: Clarify behavior of Element.getEnclosingElements in subtypes

Reviewed-by: mcimadamore, jjg

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

 /*
- * Copyright (c) 2005, 2011, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2012, 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
@@ -214,14 +214,13 @@ public interface Element {
      * Returns the elements that are, loosely speaking, directly
      * enclosed by this element.
      *
-     * A class or interface is considered to enclose the fields,
-     * methods, constructors, and member types that it directly
-     * declares.  This includes any (implicit) default constructor and
-     * the implicit {@code values} and {@code valueOf} methods of an
-     * enum type.
+     * A {@linkplain TypeElement#getEnclosedElements class or
+     * interface} is considered to enclose the fields, methods,
+     * constructors, and member types that it directly declares.
      *
-     * A package encloses the top-level classes and interfaces within
-     * it, but is not considered to enclose subpackages.
+     * A {@linkplain PackageElement#getEnclosedElements package}
+     * encloses the top-level classes and interfaces within it, but is
+     * not considered to enclose subpackages.
      *
      * Other kinds of elements are not currently considered to enclose
      * any elements; however, that may change as this API or the
@@ -231,6 +230,8 @@ public interface Element {
      * methods in {@link ElementFilter}.
      *
      * @return the enclosed elements, or an empty list if none
+     * @see PackageElement#getEnclosedElements
+     * @see TypeElement#getEnclosedElements
      * @see Elements#getAllMembers
      * @jls 8.8.9 Default Constructor
      * @jls 8.9 Enums

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

 /*
- * Copyright (c) 2005, 2011, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2012, 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
@@ -25,6 +25,8 @@
 
 package javax.lang.model.element;
 
+import java.util.List;
+
 /**
  * Represents a package program element.  Provides access to information
  * about the package and its members.
@@ -49,7 +51,7 @@ public interface PackageElement extends Element, QualifiedNameable {
 
     /**
      * Returns the simple name of this package.  For an unnamed
-     * package, an empty name is returned
+     * package, an empty name is returned.
      *
      * @return the simple name of this package or an empty name if
      * this is an unnamed package
@@ -57,6 +59,18 @@ public interface PackageElement extends Element, QualifiedNameable {
     @Override
     Name getSimpleName();
 
+    /**
+     * Returns the {@linkplain NestingKind#TOP_LEVEL top-level}
+     * classes and interfaces within this package.  Note that
+     * subpackages are <em>not</em> considered to be enclosed by a
+     * package.
+     *
+     * @return the top-level classes and interfaces within this
+     * package
+     */
+    @Override
+    List<? extends Element> getEnclosedElements();
+
     /**
      * Returns {@code true} is this is an unnamed package and {@code
      * false} otherwise.

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

 /*
- * Copyright (c) 2005, 2011, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 2012, 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
@@ -61,7 +61,12 @@ import javax.lang.model.util.*;
  */
 public interface TypeElement extends Element, Parameterizable, QualifiedNameable {
     /**
-     * {@inheritDoc}
+     * Returns the fields, methods, constructors, and member types
+     * that are directly declared in this class or interface.
+     *
+     * This includes any (implicit) default constructor and
+     * the implicit {@code values} and {@code valueOf} methods of an
+     * enum type.
      *
      * <p> Note that as a particular instance of the {@linkplain
      * javax.lang.model.element general accuracy requirements} and the
@@ -75,6 +80,7 @@ public interface TypeElement extends Element, Parameterizable, QualifiedNameable
      *
      * @return the enclosed elements in proper order, or an empty list if none
      */
+    @Override
     List<? extends Element> getEnclosedElements();
 
     /**