RFR: JDK-8267219: Javadoc method summary breaks when {@inheritDoc} from an empty parent [v3]

[Hannes Wallnöfer]

On Wed, 19 May 2021 10:38:02 GMT, liach <github.com+7806504+liach at openjdk.org> wrote:

>> src/jdk.javadoc/share/classes/jdk/javadoc/internal/doclets/formats/html/markup/ContentBuilder.java line 99:
>> 
>>> 97:         for (Content content: contents) {
>>> 98:             if (content.isValid())
>>> 99:                 return true;
>> 
>> If this is correct, then it deserves a comment. The reason is that it looks counterintuitive: I would expect isValid to have the semantics of &&, not ||.
>
> I looked at the usages of `isValid`; all of them are guarding the calls to `HtmlTree.add`, in `SerialFieldWriter`, `TagletWriter`, and `HtmlTree.add` itself. Hence, if a content builder has both valid and invalid parts, I still believe it should be added to the html tree, where only the valid subparts can be accepted. I shall document the reasons in an `implSpec` section.

I was initially unsure about this, too. But take a look at `HtmlTree.add(Content)` which handles `ContentBuilder` arguments in the following way:

        if (content instanceof ContentBuilder) {
            ((ContentBuilder) content).contents.forEach(this::add);
        }

Thus, if a ContentBuilder contains any valid Content objects, they will be added, while the invalid ones will be silently dropped.

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

PR: https://git.openjdk.java.net/jdk/pull/4066