RFR: JDK-8240697: convert builders to high-level Content blocks

[Jonathan Gibbons]

I don't have any specify examples from javadoc, but here are some 
conceptual examples:

  * if a command line option has been set, add a heading (like a <h1>)
    into some content (like a <main>)

  * for each file given on the command line, add an item (like <li>)
    into a list (like <ul>)

-- Jon


On 03/10/2020 02:16 PM, Pavel Rappo wrote:
> I agree with what you said, Jon. We should apply that pattern on a case-by-case
> basis, where practical.
>
> On a related note, I would be interested in having a look at some examples of
> "conditional" and "iterative" content. Not sure if we'll be able to do anything
> about it, but at the very least we'll see the boundaries of applicability of
> that pattern.
>
>> On 10 Mar 2020, at 20:49, Jonathan Gibbons <jonathan.gibbons at oracle.com> wrote:
>>
>> Responding to the comment about the conventions for building HTML trees ...
>>
>> My experience (including in other projects that generate HTML) is that the "After:" style you propose works well as long as it is not too deeply nested.
>>
>> It does not work so well when there is conditional content or iterative content ... and as much as I have come to appreciate streams, I believe they can be over-(ab)used in trying to force everything into a more functional paradigm.
>>
>> When the code pattern does not work well, I find I prefer to make trees "bottom up", building the leaf components, before assembling them in a single step into a larger component.   This is in comparison to creating an empty enclosing component and then building and adding the individual child components.
>>
>> And, all of these are better that some of the weirder patterns that exist in the code today.
>>
>> -- Jon
>>
>> On 03/09/2020 04:38 AM, Pavel Rappo wrote:
>>> 2. Is it just me, or it is indeed hard to comprehend the structure of the HTML
>>> being composed in some of the places? Maybe we could think of slightly bending
>>> the code formatting rules for the sake of readability where practical?
>>>
>>> Before:
>>>
>>>      HtmlTree flexHeader = HtmlTree.HEADER()
>>>              .setStyle(HtmlStyle.flexHeader)
>>>              .add(header);
>>>
>>>      HtmlTree flexContent = HtmlTree.DIV(HtmlStyle.flexContent)
>>>              .add(HtmlTree.MAIN().add(mainContents))
>>>              .add(footer);
>>>
>>>      return HtmlTree.DIV(HtmlStyle.flexBox)
>>>              .add(flexHeader)
>>>              .add(flexContent);
>>>
>>> After:
>>>
>>>      return DIV(HtmlStyle.flexBox,
>>>                 HEADER(HtmlStyle.flexHeader
>>>                     header
>>>                 ),
>>>                 DIV(HtmlStyle.flexContent,
>>>                     MAIN(mainContents),
>>>                     footer
>>>                 )
>>>             );
>>>
>>> Before:
>>>
>>>      Content li = HtmlTree.LI(HtmlStyle.blockList, table);
>>>      Content ul = HtmlTree.UL(HtmlStyle.blockList, li);
>>>      contentTree.add(ul);
>>>
>>> After:
>>>
>>>      contentTree.add(
>>>          UL(HtmlStyle.blockList,
>>>              LI(HtmlStyle.blockList, table)
>>>          )
>>>      );
>>>
>>> One added benefit of structuring HTML generation like that is that the resulting
>>> code is less error-prone. When no intermediate reference is created, it is much
>>> harder to pass a single "Content" into multiple places (which would be a bug).

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.openjdk.java.net/pipermail/javadoc-dev/attachments/20200310/f5bd0885/attachment.htm>