RFR: JDK-8240697: convert builders to high-level Content blocks
Jonathan Gibbons
jonathan.gibbons at oracle.com
Tue Mar 10 21:24:17 UTC 2020
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>
More information about the javadoc-dev
mailing list