On Wed, 19 Apr 2023 10:29:48 GMT, Pavel Rappo <pra...@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
