Here's a possible counter-patch that removes a lot of text by
delegating most of the wording to the Deque javadoc, and makes
LinkedList's Dequeness as first-class as its Listness.
diff --git a/src/share/classes/java/util/LinkedList.java
b/src/share/classes/java/util/LinkedList.java
--- a/src/share/classes/java/util/LinkedList.java
+++ b/src/share/classes/java/util/LinkedList.java
@@ -26,18 +26,9 @@
package java.util;
/**
- * Linked list implementation of the {...@code List} interface.
Implements all
- * optional list operations, and permits all elements (including
- * {...@code null}). In addition to implementing the {...@code List}
interface,
- * the {...@code LinkedList} class provides uniformly named methods to
- * {...@code get}, {...@code remove} and {...@code insert} an element at the
- * beginning and end of the list. These operations allow linked
lists to be
- * used as a stack, {...@linkplain Queue queue}, or {...@linkplain Deque
- * double-ended queue}.
- *
- * <p>The class implements the {...@code Deque} interface, providing
- * first-in-first-out queue operations for {...@code add},
- * {...@code poll}, along with other stack and deque operations.
+ * Linked list implementation of the {...@link List} and {...@link Deque}
interfaces.
+ * Implements all optional operations, and permits all elements
(including
+ * {...@code null}).
*
* <p>All of the operations perform as could be expected for a
doubly-linked
* list. Operations that index into the list will traverse the list from
Martin
On Thu, Jul 22, 2010 at 09:40, Joe Darcy <[email protected]
<mailto:[email protected]>> wrote:
Martin Buchholz wrote:
Perhaps much of the text is redundant with the specification
in the second paragraph, that talks about how a LinkedList is
also a Deque.
Perhaps the sentence starting
In addition to
should be removed, a remnant of a time when LinkedList did
not implement Deque?
Hmm. I'm more inclined to keep the revised sentence
"In addition to implementing the List interface, the LinkedList
class provides uniformly named methods to get, remove and add an
element at the beginning (operationFirst) and end (operationLast)
of the list."
and combine the next two sentences like so:
"These operations allow linked lists to be used as a stack, queue,
or deque (double-ended queue); implementing the Deque interface
includes support for first-in-first-out operations for add and poll."
What do you think?
-Joe
Martin
On Wed, Jul 21, 2010 at 19:04, Joe Darcy <[email protected]
<mailto:[email protected]> <mailto:[email protected]
<mailto:[email protected]>>> wrote:
Hello.
Please code review this simple fix to the LinkedList
javadoc for
bug 6717780 "(coll spec) LinkedList api documentation
provides the
wrong method name:" in the sentence
"In addition to implementing the List interface, the LinkedList
class provides uniformly named methods to get, remove and
insert
an element at the beginning and end of the list."
the word "insert" should be "add". I've also added text to
explicitly state that the beginning-of-list methods are
operationFirst and the end of list methods are operationLast.
Patch below, full webrev at
http://cr.openjdk.java.net/~darcy/6717780.0/
<http://cr.openjdk.java.net/%7Edarcy/6717780.0/>
<http://cr.openjdk.java.net/%7Edarcy/6717780.0/>
Thanks,
-Joe
--- old/src/share/classes/java/util/LinkedList.java
2010-07-21
18:58:12.000000000 -0700
+++ new/src/share/classes/java/util/LinkedList.java
2010-07-21
18:58:12.000000000 -0700
@@ -26,14 +26,15 @@
package java.util;
/**
- * Linked list implementation of the {...@code List} interface.
Implements all
- * optional list operations, and permits all elements
(including
- * {...@code null}). In addition to implementing the {...@code
List}
interface,
- * the {...@code LinkedList} class provides uniformly named
methods to
- * {...@code get}, {...@code remove} and {...@code insert} an
element at the
- * beginning and end of the list. These operations allow
linked
lists to be
- * used as a stack, {...@linkplain Queue queue}, or
{...@linkplain Deque
- * double-ended queue}.
+ * Linked list implementation of the {...@code List} interface.
+ * Implements all optional list operations, and permits
all elements
+ * (including {...@code null}). In addition to implementing
the {...@code
+ * List} interface, the {...@code LinkedList} class provides
uniformly
+ * named methods to {...@code get}, {...@code remove} and {...@code
add} an
+ * element at the beginning (<i>operation</i>{...@code
First}) and end
+ * (<i>operation</i>{...@code Last}) of the list. These
operations
allow
+ * linked lists to be used as a stack, {...@linkplain Queue
queue}, or
+ * {...@linkplain Deque double-ended queue}.
*
* <p>The class implements the {...@code Deque} interface,
providing
* first-in-first-out queue operations for {...@code add},
