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

[liach]

On Wed, 19 May 2021 10:02:47 GMT, Pavel Rappo <prappo at openjdk.org> wrote:

>> liach has refreshed the contents of this pull request, and previous commits have been removed. The incremental views will show differences compared to the previous content of the PR.
>
> 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.

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

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