Code review request for 6717780 "(coll spec) LinkedList api documentation provides the wrong method name"

[Martin Buchholz]

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 <joe.darcy at oracle.com> 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 <joe.darcy at oracle.com <mailto:
>> joe.darcy at oracle.com>> 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},
>>
>>
>>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.openjdk.java.net/pipermail/core-libs-dev/attachments/20100722/6abf92bd/attachment.html>