[hibernate-dev] ORM - Asciidoclet

[Steve Ebersole]

Oh, you mean it does not like HTML markup?  Not sure, we should ask Dan and
friends what is expected there from asciidoclet - I'm not sure

On Sun, Jul 15, 2018 at 8:13 AM Guillaume Smet <guillaume.smet at gmail.com>
wrote:

> No I'm talking about all the markup that appears in the output. What I
> pasted is not the source, it's the output you get in your Javadoc (with the
> <li>, the <p/> and so on).
>
> The cross references are indeed OK.
>
> On Sun, Jul 15, 2018 at 3:06 PM Steve Ebersole <steve at hibernate.org>
> wrote:
>
>> You mean the lack of rendering Javdoc cross-references ({@link ...})?
>> Otherwise, I am not sure what exactly you are getting at.
>>
>> Asciidoclet is supposed to handle Javdoc cross-references - if it is not,
>> that would be a bug in asciidoclet
>>
>> On Sun, Jul 15, 2018 at 7:58 AM Guillaume Smet <guillaume.smet at gmail.com>
>> wrote:
>>
>>> On Sun, Jul 15, 2018 at 2:13 AM Steve Ebersole <steve at hibernate.org>
>>> wrote:
>>>
>>>> We have ported things from 6 back to 5.3 so I cannot say definitively
>>>> that absolutely no javadoc in 5.3 uses asciidoc(tor).
>>>>
>>>> But feel free to disable it.
>>>>
>>>
>>> I just tried the opposite and enable Asciidoclet for the aggregated
>>> javadoc to be consistent and it leads to malformed Javadoc containing HTML
>>> markups when our Javadoc is using HTML.
>>>
>>> I think you either have all your Javadoc using Asciidoctor or you end up
>>> with some bad output.
>>>
>>> A good example is the Javadoc of CompositeNestedGeneratedValueGenerator
>>> which, with Asciidoclet enabled, looks like:
>>>
>>> For composite identifiers, defines a number of "nested" generations that
>>> need to happen to "fill" the identifier property(s). <p/> This generator is
>>> used implicitly for all composite identifier scenarios if an explicit
>>> generator is not in place. So it make sense to discuss the various
>>> potential scenarios:<ul> <li> <i>"embedded" composite identifier</i> - this
>>> is possible only in HBM mappings as &lt;composite-id/&gt; (notice the
>>> lack of both a name and class attribute declarations). The term
>>> "embedded"
>>> <http://../../../org/hibernate/mapping/Component.html#isEmbedded--> here
>>> refers to the Hibernate usage which is actually the exact opposite of the
>>> JPA meaning of "embedded". Essentially this means that the entity class
>>> itself holds the named composite pk properties. This is very similar to the
>>> JPA @IdClass usage, though without a separate pk-class for loading.
>>> </li> <li> <i>pk-class as entity attribute</i> - this is possible in both
>>> annotations (@EmbeddedId) and HBM mappings (&lt;composite-id
>>> name="idAttributeName" class="PkClassName"/&gt;) </li> <li>
>>> <i>"embedded" composite identifier with a pk-class</i> - this is the JPA
>>>  @IdClass use case and is only possible in annotations </li> </ul> <p/>
>>> Most of the grunt work is done in Component
>>> <http://../../../org/hibernate/mapping/Component.html>.
>>>
>>> Did I miss something?
>>>
>>> --
>>> Guillaume
>>>
>>