RFR: 8266571: Sequenced Collections [v7]

[Stuart Marks]

On Wed, 19 Apr 2023 10:29:48 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> src/java.base/share/classes/java/util/concurrent/CopyOnWriteArrayList.java line 409:
>> 
>>> 407:      * {@inheritDoc}
>>> 408:      */
>>> 409:     public E getFirst() {
>> 
>> 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.
>
>> 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?

@pavelrappo Arrrrggh.

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

All this "trivial" stuff is generating a lot of work! :-) Well, no big deal, Joe D still has more CSR comments coming.

I didn't know about the need to specify `@throws` in order to generate the throws-clauses in the docs. Ah, well, turns out it wasn't THAT bad to run through the hierarchy and check all the inherited methods. Done.

As an aside, I note that some methods such as ArrayList.addFirst/addLast had this javadoc:

    /**
     * @inheritDoc
     */

It didn't appear at all in the javadoc output, I guess because of `--override-methods=summary`. Not surprising in isolation, but it seemed strange because the getX and removeX methods were in the detail section but the addX methods seemed "missing". Is there a way to inherit the doc from a superclass but force a particular method to have its details included? It's kind of moot because these are also missing a `@since` tag, and adding that did cause the method detail to be included. Seems like the summary/detail stuff still needs some things to be worked out.

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

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