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

[Joe Darcy]

Yes, that is more concise while still conveying the needed information.  
I'll be a reviewer if you want to push your counter-patch.

-Joe

Martin Buchholz wrote:
> 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 
> <mailto: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> <mailto: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},
>
>
>
>