Hi, Are we using Asciidoc javadoc in the current tree (i.e. not 6)? With JDK 11, when ./gradlew :hibernate-core:javadoc is executed and this doclet is enabled, I have the following error: javadoc: error - invalid flag: -Xdoclint:none In the javadoc -X help, it says that doclint is "Provided by the Standard doclet". Removing the asciidoclet declaration fixes the issue. As asciidoclet is not enabled in the aggregateJavadocs task, I'm under the impression that it is not used. Could someone confirm this? Thanks! -- Guillaume _______________________________________________ hibernate-dev mailing list hibernate-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/hibernate-dev

On Sun, Jul 15, 2018 at 2:13 AM Steve Ebersole <steve(a)hibernate.org&gt; 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

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(a)hibernate.org&gt; 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(a)gmail.com&gt; > wrote: > >> On Sun, Jul 15, 2018 at 2:13 AM Steve Ebersole <steve(a)hibernate.org&gt; >> 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 >> >

On Sun, Jul 15, 2018 at 3:16 PM Steve Ebersole <steve(a)hibernate.org&gt; wrote: > 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 > Yes, exactly. HTML output is rendered escaped, which is expected if it considers all our Javadoc content as potential Asciidoctor. For now, I'll disable it in 5.3 as we're not even sure we have Asciidoctor in it. But we should check that for 6 as, if it's expected, we would have to rewrite all the existing Javadoc as Asciidoctor. I posted something on the Asciidoctor discussion forum: http://discuss.asciidoctor.org/Migrating-to-Asciidoclet-progressively-td6... . -- Guillaume