RFR: 8266571: Sequenced Collections [v7]

[Pavel Rappo]

On Wed, 19 Apr 2023 04:36:28 GMT, Chen Liang <liach at openjdk.org> wrote:

> Javadoc will automatically copy the specification from the overridden method, so the javadoc block is not necessary and can be replaced by an `@Override` to indicate inheritance.

I guess, this PR has converged enough for us to discuss some trivial stuff; so here it goes.

While you are right when saying that a doc comment consisting of a lone `{@inheritDoc}` is -- and I'm paraphrasing here -- the same as no comment at all, such a comment effectively is a copy of the overridden method _main description_, which is the part of a doc comment from its beginning to the first block tag or the end of the comment (if the comment has no block tags).

Parameters, return value and exception information -- all those are copied because they are mentioned in the method declaration. While this might give an impression that it's the result of `{@inheritDoc}`, it is important to understand that it isn't. For example, since runtime exceptions and errors aren't required to be mentioned in the `throws` clause of a method declaration, no `@throws` tags corresponding to such throwables will be copied automatically; the doc comment has to explicitly inherit those. In our case, either would do:

    /**
     * @throws NoSuchElementException {@inheritDoc}
     */
    public E getFirst() {

    /**
     * {@inheritDoc}
     * @throws NoSuchElementException {@inheritDoc}
     */
    public E getFirst() {

Speaking of which: @stuart-marks, do you think you could add those everywhere?

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

PR Review Comment: https://git.openjdk.org/jdk/pull/7387#discussion_r1171145153