RFR: JDK-8199216: Quadratic layout time with nested nodes and pseudo-class in style sheet [v8]

[John Hendrikx]

On Thu, 3 Aug 2023 15:24:40 GMT, Marius Hanl <mhanl at openjdk.org> wrote:

>> There is an `@Override` annotation, javadoc will do the right thing.
>
> So it is only needed when we want to add something to the javadoc coming from the superclass?

Yes, that's correct.  `@inheritDoc` is only needed when you want to add your own documentation, and you can then choose where to have the original docs "inserted".   See last part of this quote from the standard doclet documentation (at https://docs.oracle.com/en/java/javase/20/docs/specs/javadoc/doc-comment-spec.html):

## Comment Inheritance
### Class and Interface Inheritance
Comment inheritance occurs in all possible cases of inheritance from classes and interfaces:

- When a method in a class overrides a method in a superclass
- When a method in an interface overrides a method in a superinterface
- When a method in a class implements a method in an interface
In the first two cases, the standard doclet generates the subheading "Overrides" in the documentation for the overriding method. A link to the method being overridden is included, whether or not the comment is inherited.

In the third case, when a method in a specified class implements a method in an interface, the standard doclet generates the subheading "Specified by" in the documentation for the overriding method. A link to the method being implemented is included, whether or not the comment is inherited.

### Method Comment Inheritance
The standard doclet allows method comment inheritance in classes and interfaces to fill in missing text or to explicitly inherit method comments. Constructors, fields, and nested classes do not inherit documentation comments.

Note: The source file for an inherited method must be on the path specified by the -sourcepath option for the documentation comment to be available to copy. Neither the class nor its package needs to be passed in on the command line.

### Fill in Missing Text
When a main description, or @return, @param, or @throws tag is missing from a method comment, the information is copied from the method it overrides or implements (if any).

When an @param tag for a particular parameter is missing, the comment for that parameter is copied from the method further up the inheritance hierarchy. When an @throws tag for a particular exception is missing, the @throws tag is copied only when that exception is declared.

### Explicit Inheritance
Insert the {@inheritDoc} inline tag in a method main description or @return, @param, or @throws tag comment. The corresponding inherited main description or tag comment is copied into that spot.

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

PR Review Comment: https://git.openjdk.org/jfx/pull/1076#discussion_r1283979152