On Wed, 19 May 2021 11:27:39 GMT, Hannes Wallnöfer <hann...@openjdk.org> wrote:
>> 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.
Something is wrong, but I cannot quite put my finger on it. I think this PR
merely highlights a pre-existing issue that should be investigated separately.
I'm surprised by the concept of validity for the **generated** content. I'm
also surprised by the fact that a part of the content can be silently omitted
depending on whether or not that part is valid. This suggests that javadoc uses
instances of HtmlTree as its data model which it shouldn't do.
-------------
PR: https://git.openjdk.java.net/jdk/pull/4066
