[hibernate-dev] ORM - Asciidoclet

[Guillaume Smet]

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"
<../../../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 <../../../org/hibernate/mapping/Component.html>.

Did I miss something?

-- 
Guillaume