On Wed, 19 Apr 2023 04:36:28 GMT, Chen Liang <li...@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
