Should the documentation state peekFirst() as equivalent to Stack's peek()?

[Turkhan Badalov]

Hi!

After this commit
https://github.com/openjdk/jdk/commit/1846a65e32624f6da691c1072f44fcb762b43233#diff-f7198d7dbc99fe4e161d39db820508c743fe03ecf004085625ab241255c98e76L164,
I was expecting the docs to get updated with the release of Java 23.

However, the typo is still there:
https://docs.oracle.com/en/java/javase/23/docs/api/java.base/java/util/Deque.html

Wondering when is the change supposed to take effect or does it mean the
fix is not complete?

Regards,
Turkhan


On Thu, Jul 25, 2024 at 3:57 PM Chen Liang <chen.l.liang at oracle.com> wrote:

> Hi Turkhan, this mail belongs to core-libs-dev list. I have forwarded your
> mail to the right list.
>
> Indeed, we should claim that peek() is equivalent to peekFirst(); the
> information in stack section should be a typo, as peek() being the same as
> peekFirst() is claimed by the deque section and the peek() specification.
>
> I have created a ticket on the Java Bug System to track this issue: [JDK-8337205]
> Typo in Stack vs Deque Method table in Deque specification - Java Bug
> System (openjdk.org) <https://bugs.openjdk.org/browse/JDK-8337205>
>
> Feel free to open a pull request to jdk to fix this bug.
>
> Best, Chen Liang
> ------------------------------
> *From:* jdk-dev <jdk-dev-retn at openjdk.org> on behalf of Turkhan Badalov <
> badalov.turxan at gmail.com>
> *Sent:* Thursday, July 25, 2024 4:58 AM
> *To:* jdk-dev at openjdk.org <jdk-dev at openjdk.org>
> *Subject:* Should the documentation state peekFirst() as equivalent to
> Stack's peek()?
>
> Here is the table "Comparison of Stack and Deque methods" that lists
> equivalent Deque methods compared to Stack methods:
> https://docs.oracle.com/en/java/javase/22/docs/api/java.base/java/util/Deque.html
>
> At the moment, getFirst() is said to be equivalent to peek(). Since peek()
> doesn't throw an exception when the queue/stack is empty, peekFirst() could
> be a better equivalent because getFirst() throws.
>
> In fact, the documentation of the peek() method itself says that this
> method is equivalent to peekFirst():
> https://docs.oracle.com/en/java/javase/22/docs/api/java.base/java/util/Deque.html#peek()
> .
>
> If this should be posted somewhere else, please let me know. I am still
> new to using mailing lists. Cheers.
>
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.org/pipermail/core-libs-dev/attachments/20241106/cf3dd8b9/attachment.htm>