changeset 22114:e9be73bceec1

8031142: AbstractCollection and AbstractList should specify their default implementation using @implSpec Reviewed-by: martin, psandoz
author chegar
date Tue, 07 Jan 2014 12:59:32 +0000
parents a1ee9743f4ee
children 27bd4fa78407
files jdk/src/share/classes/java/util/AbstractCollection.java jdk/src/share/classes/java/util/AbstractList.java
diffstat 2 files changed, 52 insertions(+), 26 deletions(-) [+]
line wrap: on
line diff
--- a/jdk/src/share/classes/java/util/AbstractCollection.java	Wed Jul 05 19:25:40 2017 +0200
+++ b/jdk/src/share/classes/java/util/AbstractCollection.java	Tue Jan 07 12:59:32 2014 +0000
@@ -80,7 +80,8 @@
     /**
      * {@inheritDoc}
      *
-     * <p>This implementation returns <tt>size() == 0</tt>.
+     * @implSpec
+     * This implementation returns <tt>size() == 0</tt>.
      */
     public boolean isEmpty() {
         return size() == 0;
@@ -89,7 +90,8 @@
     /**
      * {@inheritDoc}
      *
-     * <p>This implementation iterates over the elements in the collection,
+     * @implSpec
+     * This implementation iterates over the elements in the collection,
      * checking each element in turn for equality with the specified element.
      *
      * @throws ClassCastException   {@inheritDoc}
@@ -112,7 +114,8 @@
     /**
      * {@inheritDoc}
      *
-     * <p>This implementation returns an array containing all the elements
+     * @implSpec
+     * This implementation returns an array containing all the elements
      * returned by this collection's iterator, in the same order, stored in
      * consecutive elements of the array, starting with index {@code 0}.
      * The length of the returned array is equal to the number of elements
@@ -146,7 +149,8 @@
     /**
      * {@inheritDoc}
      *
-     * <p>This implementation returns an array containing all the elements
+     * @implSpec
+     * This implementation returns an array containing all the elements
      * returned by this collection's iterator in the same order, stored in
      * consecutive elements of the array, starting with index {@code 0}.
      * If the number of elements returned by the iterator is too large to
@@ -249,7 +253,8 @@
     /**
      * {@inheritDoc}
      *
-     * <p>This implementation always throws an
+     * @implSpec
+     * This implementation always throws an
      * <tt>UnsupportedOperationException</tt>.
      *
      * @throws UnsupportedOperationException {@inheritDoc}
@@ -265,7 +270,8 @@
     /**
      * {@inheritDoc}
      *
-     * <p>This implementation iterates over the collection looking for the
+     * @implSpec
+     * This implementation iterates over the collection looking for the
      * specified element.  If it finds the element, it removes the element
      * from the collection using the iterator's remove method.
      *
@@ -304,7 +310,8 @@
     /**
      * {@inheritDoc}
      *
-     * <p>This implementation iterates over the specified collection,
+     * @implSpec
+     * This implementation iterates over the specified collection,
      * checking each element returned by the iterator in turn to see
      * if it's contained in this collection.  If all elements are so
      * contained <tt>true</tt> is returned, otherwise <tt>false</tt>.
@@ -323,7 +330,8 @@
     /**
      * {@inheritDoc}
      *
-     * <p>This implementation iterates over the specified collection, and adds
+     * @implSpec
+     * This implementation iterates over the specified collection, and adds
      * each object returned by the iterator to this collection, in turn.
      *
      * <p>Note that this implementation will throw an
@@ -349,7 +357,8 @@
     /**
      * {@inheritDoc}
      *
-     * <p>This implementation iterates over this collection, checking each
+     * @implSpec
+     * This implementation iterates over this collection, checking each
      * element returned by the iterator in turn to see if it's contained
      * in the specified collection.  If it's so contained, it's removed from
      * this collection with the iterator's <tt>remove</tt> method.
@@ -383,7 +392,8 @@
     /**
      * {@inheritDoc}
      *
-     * <p>This implementation iterates over this collection, checking each
+     * @implSpec
+     * This implementation iterates over this collection, checking each
      * element returned by the iterator in turn to see if it's contained
      * in the specified collection.  If it's not so contained, it's removed
      * from this collection with the iterator's <tt>remove</tt> method.
@@ -417,7 +427,8 @@
     /**
      * {@inheritDoc}
      *
-     * <p>This implementation iterates over this collection, removing each
+     * @implSpec
+     * This implementation iterates over this collection, removing each
      * element using the <tt>Iterator.remove</tt> operation.  Most
      * implementations will probably choose to override this method for
      * efficiency.
--- a/jdk/src/share/classes/java/util/AbstractList.java	Wed Jul 05 19:25:40 2017 +0200
+++ b/jdk/src/share/classes/java/util/AbstractList.java	Tue Jan 07 12:59:32 2014 +0000
@@ -87,7 +87,8 @@
      * classes should clearly specify in their documentation any restrictions
      * on what elements may be added.
      *
-     * <p>This implementation calls {@code add(size(), e)}.
+     * @implSpec
+     * This implementation calls {@code add(size(), e)}.
      *
      * <p>Note that this implementation throws an
      * {@code UnsupportedOperationException} unless
@@ -119,7 +120,8 @@
     /**
      * {@inheritDoc}
      *
-     * <p>This implementation always throws an
+     * @implSpec
+     * This implementation always throws an
      * {@code UnsupportedOperationException}.
      *
      * @throws UnsupportedOperationException {@inheritDoc}
@@ -135,7 +137,8 @@
     /**
      * {@inheritDoc}
      *
-     * <p>This implementation always throws an
+     * @implSpec
+     * This implementation always throws an
      * {@code UnsupportedOperationException}.
      *
      * @throws UnsupportedOperationException {@inheritDoc}
@@ -151,7 +154,8 @@
     /**
      * {@inheritDoc}
      *
-     * <p>This implementation always throws an
+     * @implSpec
+     * This implementation always throws an
      * {@code UnsupportedOperationException}.
      *
      * @throws UnsupportedOperationException {@inheritDoc}
@@ -167,7 +171,8 @@
     /**
      * {@inheritDoc}
      *
-     * <p>This implementation first gets a list iterator (with
+     * @implSpec
+     * This implementation first gets a list iterator (with
      * {@code listIterator()}).  Then, it iterates over the list until the
      * specified element is found or the end of the list is reached.
      *
@@ -191,7 +196,8 @@
     /**
      * {@inheritDoc}
      *
-     * <p>This implementation first gets a list iterator that points to the end
+     * @implSpec
+     * This implementation first gets a list iterator that points to the end
      * of the list (with {@code listIterator(size())}).  Then, it iterates
      * backwards over the list until the specified element is found, or the
      * beginning of the list is reached.
@@ -220,7 +226,8 @@
      * Removes all of the elements from this list (optional operation).
      * The list will be empty after this call returns.
      *
-     * <p>This implementation calls {@code removeRange(0, size())}.
+     * @implSpec
+     * This implementation calls {@code removeRange(0, size())}.
      *
      * <p>Note that this implementation throws an
      * {@code UnsupportedOperationException} unless {@code remove(int
@@ -237,7 +244,8 @@
     /**
      * {@inheritDoc}
      *
-     * <p>This implementation gets an iterator over the specified collection
+     * @implSpec
+     * This implementation gets an iterator over the specified collection
      * and iterates over it, inserting the elements obtained from the
      * iterator into this list at the appropriate position, one at a time,
      * using {@code add(int, E)}.
@@ -269,7 +277,8 @@
     /**
      * Returns an iterator over the elements in this list in proper sequence.
      *
-     * <p>This implementation returns a straightforward implementation of the
+     * @implSpec
+     * This implementation returns a straightforward implementation of the
      * iterator interface, relying on the backing list's {@code size()},
      * {@code get(int)}, and {@code remove(int)} methods.
      *
@@ -291,7 +300,8 @@
     /**
      * {@inheritDoc}
      *
-     * <p>This implementation returns {@code listIterator(0)}.
+     * @implSpec
+     * This implementation returns {@code listIterator(0)}.
      *
      * @see #listIterator(int)
      */
@@ -302,7 +312,8 @@
     /**
      * {@inheritDoc}
      *
-     * <p>This implementation returns a straightforward implementation of the
+     * @implSpec
+     * This implementation returns a straightforward implementation of the
      * {@code ListIterator} interface that extends the implementation of the
      * {@code Iterator} interface returned by the {@code iterator()} method.
      * The {@code ListIterator} implementation relies on the backing list's
@@ -448,7 +459,8 @@
     /**
      * {@inheritDoc}
      *
-     * <p>This implementation returns a list that subclasses
+     * @implSpec
+     * This implementation returns a list that subclasses
      * {@code AbstractList}.  The subclass stores, in private fields, the
      * offset of the subList within the backing list, the size of the subList
      * (which can change over its lifetime), and the expected
@@ -495,8 +507,9 @@
      * the two lists are <i>equal</i>.  (Two elements {@code e1} and
      * {@code e2} are <i>equal</i> if {@code (e1==null ? e2==null :
      * e1.equals(e2))}.)  In other words, two lists are defined to be
-     * equal if they contain the same elements in the same order.<p>
+     * equal if they contain the same elements in the same order.
      *
+     * @implSpec
      * This implementation first checks if the specified object is this
      * list. If so, it returns {@code true}; if not, it checks if the
      * specified object is a list. If not, it returns {@code false}; if so,
@@ -529,7 +542,8 @@
     /**
      * Returns the hash code value for this list.
      *
-     * <p>This implementation uses exactly the code that is used to define the
+     * @implSpec
+     * This implementation uses exactly the code that is used to define the
      * list hash function in the documentation for the {@link List#hashCode}
      * method.
      *
@@ -555,7 +569,8 @@
      * improve the performance of the {@code clear} operation on this list
      * and its subLists.
      *
-     * <p>This implementation gets a list iterator positioned before
+     * @implSpec
+     * This implementation gets a list iterator positioned before
      * {@code fromIndex}, and repeatedly calls {@code ListIterator.next}
      * followed by {@code ListIterator.remove} until the entire range has
      * been removed.  <b>Note: if {@code ListIterator.remove} requires linear