Description list support for JavaDocs (#2213)

[IgnatBeresnev]

#2213

[IgnatBeresnev]

I thought about extracting it to a separate enum ListContentStyle, but it seems unlikely that we'll ever add anything else there, so probably not worth it

[vmishenev]

• This does not work with:

<dl>
    <div>
        <dt>Term1</dt>
        <dd>Desc2</dd>
    </div>
    <div>
        <dt>Term2</dt>
        <dd>Desc2</dd>
    </div>
</dl> 

• What is about another tags, e.g. dfn?

[IgnatBeresnev]

This does not work with:

<dl>
  <div>
       <dt>Term1</dt>
       <dd>Desc2</dd>
   </div>
   <div>
       <dt>Term2</dt>
       <dd>Desc2</dd>
   </div>
</dl> 

Unfortunately, it seems to be the limitation of the content model in general since there's no separate content type for list items, which are now handled as ContentGroup. For instance, for ul/ol, we consider all children to be li, even if they're not. In javadocs it results in this

    /**
     * <ul>
     *     <div>one</div>
     *     <div>two</div>
     * </ul>
     */

being rendered as

• one
• two

---

As for description lists, dl is ContentList and dt/dd are ContentGroup with a list style, and just like for ol/ul, I only look for list items among the top level children. If we want to be able to render nested dd/dt using the current content model, I see the following options:

• Map dt/dd into ContentList (but this won't work for ol/ul due to nested lists)
• Add an if (node.hasStyle(DescriptionTag)) into buildGroup

And I don't like either solution :)

We could extend the content model and introduce ContentListItem and render it separately, but I would expect you not to like it ;)

All in all, I don't see an easy way out, let me know if you do. Hopefully your example is a rare case and the solution can be postponed

[IgnatBeresnev]

What is about another tags, e.g. dfn?

It seems like dfn can indeed be used within description lists, but it's not exclusive to that, so I think it falls more under "support more javadoc html tags", which I indeed didn't do. We can plan it as a separate issue/pr

[vmishenev]

It seems like dfn can indeed be used within description lists, but it's not exclusive to that

It is a good case to think about the design of styles beforehand.

We can plan it as a separate issue/pr

Can you open an issue for it?

[vmishenev]

    /**
     * <ul>
     *     <div>one</div>
     *     <div>two</div>
     * </ul>
     */

It is impossible for HTML scheme.
See https://html.spec.whatwg.org/multipage/grouping-content.html#the-ul-element

[vmishenev]

Please add my case to tests