https://github.com/asciidoctor/asciidoclet/pull/91

- work in progress as the PR did not fix the problems

build.gradle

@@ -39,6 +39,12 @@ allprojects {
 				dirs "${System.env.ADDITIONAL_REPO}"
 			}
 		}
+		// Needed atm for asciidoclet PR-91, which does not seem to work anyway :(
+		// todo (6.0) : remove once/if PR-91 ever works and becomes part of asciidoclet proper
+		maven {
+			name 'jboss-snapshots-repository'
+			url 'https://repository.jboss.org/nexus/content/repositories/snapshots'
+		}
 	}
 	apply plugin: 'idea'
 	apply plugin: 'eclipse'

gradle/java-module.gradle

@@ -65,9 +65,6 @@ configurations {
 	provided {
 		description = 'Non-exported compile-time dependencies.'
 	}
-	asciidoclet {
-		description = 'Dependencies for Asciidoctor Javadoc taglet'
-	}
 }
 
 configurations.all*.exclude group: 'xml-apis', module: 'xml-apis'
@@ -112,8 +109,6 @@ dependencies {
 	testRuntime( libraries.informix )
 	testRuntime( libraries.hana )
 
-	asciidoclet( libraries.asciidoclet )
-
 	if ( db.equalsIgnoreCase( 'oracle' ) ) {
 		testRuntime( libraries.oracle ) {
 			exclude group: 'com.oracle.jdbc', module: 'xmlparserv2'

gradle/libraries.gradle

@@ -182,10 +182,13 @@ ext {
             jboss_ejb_spec_jar          : 'org.jboss.spec.javax.ejb:jboss-ejb-api_3.2_spec:1.0.0.Final',
             jboss_annotation_spec_jar   : 'org.jboss.spec.javax.annotation:jboss-annotations-api_1.2_spec:1.0.0.Final',
 
-            asciidoclet : 'org.asciidoctor:asciidoclet:1.+',
-            //asciidoclet : 'org.asciidoctor:asciidoclet:1.5.7-SNAPSHOT'
+            graalvm_nativeimage         : "org.graalvm.nativeimage:svm:${graalvmVersion}",
 
-            graalvm_nativeimage         : "org.graalvm.nativeimage:svm:${graalvmVersion}"
+            //asciidoclet : 'org.asciidoctor:asciidoclet:1.+',
+            // Use the SNAPSHOT temporarily to validate asciidoclet's PR-91 - https://github.com/asciidoctor/asciidoclet/pull/91
+            //		- which does not seem to work anyway
+            // todo (6.0) : come back and verify whether this ever works
+            asciidoclet : 'org.asciidoctor:asciidoclet:1.5.7-SNAPSHOT'
         ]
 }
 

gradle/published-java-module.gradle

@@ -12,6 +12,20 @@ apply from: rootProject.file( 'gradle/publishing-pom.gradle' )
 
 
 
+// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+// Configurations and Dependencies
+
+configurations {
+	asciidoclet {
+		description = 'Dependencies for Asciidoctor Javadoc taglet'
+	}
+}
+
+dependencies {
+	asciidoclet( libraries.asciidoclet )
+}
+
+
 // ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 // Jar
 
@@ -87,8 +101,12 @@ javadoc {
 	final int currentYear = new GregorianCalendar().get( Calendar.YEAR )
 
 	configure( options ) {
-//		docletpath = configurations.asciidoclet.files.asType(List)
-//		doclet = 'org.asciidoctor.Asciidoclet'
+		// this is the config needed to use asciidoclet for Javadoc rendering.  It relies on a build from John's PR @ https://github.com/asciidoctor/asciidoclet/pull/91
+		// however, the PR does not work for me in that Javadocs with `@asciidoclet` are not rendered using asciidoc(tor/let).  Also tried the preferable `@asciidoc`
+		// with the same result.  Leaving all this config in place however as the outcome is the same as not enabling it.
+		// todo (6.0) : need to find out why the asciidoclet PR does not work
+		docletpath = configurations.asciidoclet.files.asType(List)
+		doclet = 'org.asciidoctor.Asciidoclet'
 		windowTitle = "$project.name JavaDocs"
 		docTitle = "$project.name JavaDocs ($project.version)"
 		bottom = "Copyright &copy; 2001-$currentYear <a href=\"http://redhat.com\">Red Hat, Inc.</a>  All Rights Reserved."
@@ -116,10 +134,14 @@ javadoc {
 			addStringOption( 'Xdoclint:none', '-quiet' )
 		}
 
+		// by default, exclude the files from Asciidoclet processing
+		// add the @asciidoclet tag to enable Asciidoclet on a particular file
+		options.addStringOption( '-exclude-asciidoclet-process', '**' )
+
 		tags(
 				'todo:X"',
 				'apiNote:a:"API Note:"',
-				'implSpec:a:"Implementation Requirements:"',
+				'implSpec:a:"Implementation Specification:"',
 				'implNote:a:"Implementation Note:"'
 		)
 	}

hibernate-core/src/main/java/org/hibernate/sql/ast/spi/SqlSelection.java

@@ -13,7 +13,7 @@ import org.hibernate.sql.ast.SqlAstWalker;
 import org.hibernate.type.descriptor.ValueExtractor;
 
 /**
- * @asciidoc
+ * @asciidoclet
  *
  * Represents a selection at the SQL/JDBC level.  Essentially made up of:
  *