changeset 1180:cf2496340fef

7130768: Clarify behavior of Element.getEnclosingElements in subtypes Reviewed-by: mcimadamore, jjg
author darcy
date Wed, 18 Jan 2012 16:43:59 -0800
parents f00afa80f1f0
children 99261fc7d95d
files src/share/classes/javax/lang/model/element/Element.java src/share/classes/javax/lang/model/element/PackageElement.java src/share/classes/javax/lang/model/element/TypeElement.java
diffstat 3 files changed, 33 insertions(+), 12 deletions(-) [+]
line wrap: on
line diff
--- a/src/share/classes/javax/lang/model/element/Element.java	Wed Jan 18 11:00:55 2012 -0800
+++ b/src/share/classes/javax/lang/model/element/Element.java	Wed Jan 18 16:43:59 2012 -0800
@@ -1,5 +1,5 @@
 /*
- * 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 @@
      * 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 @@
      * 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
--- a/src/share/classes/javax/lang/model/element/PackageElement.java	Wed Jan 18 11:00:55 2012 -0800
+++ b/src/share/classes/javax/lang/model/element/PackageElement.java	Wed Jan 18 16:43:59 2012 -0800
@@ -1,5 +1,5 @@
 /*
- * 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 @@
 
     /**
      * 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
@@ -58,6 +60,18 @@
     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.
      *
--- a/src/share/classes/javax/lang/model/element/TypeElement.java	Wed Jan 18 11:00:55 2012 -0800
+++ b/src/share/classes/javax/lang/model/element/TypeElement.java	Wed Jan 18 16:43:59 2012 -0800
@@ -1,5 +1,5 @@
 /*
- * 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 @@
  */
 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 @@
      *
      * @return the enclosed elements in proper order, or an empty list if none
      */
+    @Override
     List<? extends Element> getEnclosedElements();
 
     /**