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]> 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]>> 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},
>>
>>
>>
>
