RFR: 8311517: ArrayList javadoc improvements related to sequenced collection updates

[Stuart Marks]

On Wed, 26 Jul 2023 11:02:20 GMT, dan1st <duke at openjdk.org> wrote:

> The [JEP for sequenced collections](https://openjdk.org/jeps/431) would add addFirst(), removeFirst() and reversed() methods to lists.
> However, the Javadoc of List mentions:
>  > The size, isEmpty, get, set, iterator, and listIterator operations run in constant time. The add operation runs in amortized constant time, that is, adding n elements requires O(n) time. All of the other operations run in linear time (roughly speaking). The constant factor is low compared to that for the LinkedList implementation.
> 
> This PR updates that Javadoc to factor in the new methods introduced by JEP 431.
> 
> https://bugs.openjdk.org/browse/JDK-8311517
> https://mail.openjdk.org/pipermail/core-libs-dev/2023-June/107328.html
> https://mail.openjdk.org/pipermail/core-libs-dev/2023-July/109637.html
> 
> This PR only affects documentation.

Hi, thanks for working on this.

I've changed the bug summary line to be more descriptive:

> Add performance information to ArrayList javadoc

The PR title needs to be changed to match. I hope this is ok.

Regarding the text of the change: should getFirst() and getLast() be mentioned? They were added by Sequenced Collections, and they run in constant time. Also, while add() and addLast() run in amortized constant time (because of the possibility of array growth) removeLast() runs in absolute constant time; it never copies or reallocates the array.

-------------

PR Comment: https://git.openjdk.org/jdk/pull/15040#issuecomment-1652555426