HHH-17047 - Follow up tasks for Gradle 8.2 upgrade

- toolchains
- lazy Task creation
- documentation (documentation/ and release/) tasks

documentation/documentation.gradle

@@ -216,7 +216,7 @@ def aggregateJavadocsTask = tasks.register( "aggregateJavadocs", Javadoc ) {
 	maxMemory = '512m'
 	configure( options ) {
 		overview = 'src/javadoc/overview.html'
-		stylesheetFile = new File( projectDir, 'src/javadoc/stylesheet.css' )
+		stylesheetFile = project.file( 'src/javadoc/stylesheet.css' )
 		windowTitle = 'Hibernate JavaDocs'
 		docTitle = "Hibernate JavaDoc ($project.version)"
 		bottom = "Copyright &copy; 2001-$currentYear <a href=\"https://redhat.com\">Red Hat, Inc.</a>  All Rights Reserved."

hibernate-core/src/main/java/org/hibernate/Incubating.java

@@ -6,6 +6,7 @@
  */
 package org.hibernate;
 
+import java.lang.annotation.Documented;
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
@@ -30,5 +31,6 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  */
 @Target({PACKAGE, TYPE, ANNOTATION_TYPE, METHOD, FIELD, CONSTRUCTOR})
 @Retention(RUNTIME)
+@Documented
 public @interface Incubating {
 }

hibernate-core/src/main/java/org/hibernate/Internal.java

@@ -6,6 +6,7 @@
  */
 package org.hibernate;
 
+import java.lang.annotation.Documented;
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
@@ -29,6 +30,7 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  */
 @Target({PACKAGE, TYPE, METHOD, FIELD, CONSTRUCTOR})
 @Retention(RUNTIME)
+@Documented
 public @interface Internal {
 }
 

hibernate-core/src/main/java/org/hibernate/Remove.java

@@ -6,6 +6,7 @@
  */
 package org.hibernate;
 
+import java.lang.annotation.Documented;
 import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
@@ -33,5 +34,6 @@ import static java.lang.annotation.RetentionPolicy.RUNTIME;
  */
 @Target({METHOD, FIELD, TYPE, PACKAGE, CONSTRUCTOR, TYPE_PARAMETER, TYPE_USE})
 @Retention(RUNTIME)
+@Documented
 public @interface Remove {
 }

local-build-plugins/src/main/java/org/hibernate/orm/properties/AsciiDocWriter.java

@@ -63,15 +63,13 @@ public class AsciiDocWriter {
 			writer.write( '\n' );
 
 			for ( SettingDescriptor settingDescriptor : sectionSettingDescriptors ) {
-				writer.write( ANCHOR_START );
+				writeSettingAnchor( settingDescriptor, writer );
-				writer.write( settingDescriptor.getName() );
-				writer.write( "]] " );
 
-				writer.write( '`' );
+				writeSettingName( settingDescriptor, writer );
-				writer.write( settingDescriptor.getName() );
-				writer.write( '`' );
 				writer.write( "::\n" );
 
+				writeLifecycleNotes( settingDescriptor, writer );
+
 				writer.write( settingDescriptor.getJavadoc() );
 
 				writer.write( "\n\n'''\n" );
@@ -81,6 +79,42 @@ public class AsciiDocWriter {
 		}
 	}
 
+	private static void writeLifecycleNotes(SettingDescriptor settingDescriptor, FileWriter writer) throws IOException {
+		// NOTE : at the moment, there is at least one setting that is both which fundamentally seems wrong
+		if ( settingDescriptor.isIncubating() ) {
+			writer.write( "NOTE:: _This setting is considered incubating_\n\n" );
+		}
+		if ( settingDescriptor.isDeprecated() ) {
+			writer.write( "WARN:: _This setting is considered deprecated_\n\n" );
+		}
+	}
+
+	private static void writeSettingName(SettingDescriptor settingDescriptor, FileWriter writer) throws IOException {
+		writer.write( "`" );
+		if ( settingDescriptor.isDeprecated() ) {
+			writer.write( "[.line-through]#" );
+		}
+		else {
+			writer.write( '*' );
+		}
+
+		writer.write( settingDescriptor.getName() );
+
+		if ( settingDescriptor.isDeprecated() ) {
+			writer.write( '#' );
+		}
+		else {
+			writer.write( '*' );
+		}
+		writer.write( '`' );
+	}
+
+	private static void writeSettingAnchor(SettingDescriptor settingDescriptor, Writer writer) throws IOException {
+		writer.write( ANCHOR_START );
+		writer.write( settingDescriptor.getName() );
+		writer.write( "]] " );
+	}
+
 	private static void tryToWriteLine(Writer writer, String prefix, String value, String... other) {
 		try {
 			writer.write( prefix );

local-build-plugins/src/main/java/org/hibernate/orm/properties/SettingDescriptor.java

@@ -20,16 +20,22 @@ public class SettingDescriptor {
 	private final String settingsClassName;
 	private final String settingFieldName;
 	private final String javadoc;
+	private final boolean deprecated;
+	private final boolean incubating;
 
 	public SettingDescriptor(
 			String name,
 			String settingsClassName,
 			String settingFieldName,
-			String javadoc) {
+			String javadoc,
+			boolean deprecated,
+			boolean incubating) {
 		this.name = name;
 		this.settingsClassName = settingsClassName;
 		this.settingFieldName = settingFieldName;
 		this.javadoc = javadoc;
+		this.deprecated = deprecated;
+		this.incubating = incubating;
 	}
 
 	/**
@@ -53,4 +59,12 @@ public class SettingDescriptor {
 	public String getSettingFieldName() {
 		return settingFieldName;
 	}
+
+	public boolean isDeprecated() {
+		return deprecated;
+	}
+
+	public boolean isIncubating() {
+		return incubating;
+	}
 }

local-build-plugins/src/main/java/org/hibernate/orm/properties/SettingsCollector.java

@@ -96,7 +96,9 @@ public class SettingsCollector {
 								className,
 								simpleFieldName,
 								publishedJavadocsUrl
-						)
+						),
+						interpretDeprecation( fieldJavadocElement ),
+						interpretIncubation( fieldJavadocElement )
 				);
 				docSectionSettings.add( settingDescriptor );
 			}
@@ -179,6 +181,28 @@ public class SettingsCollector {
 		return value;
 	}
 
+	private static boolean interpretDeprecation(Element fieldJavadocElement) {
+		// A setting is considered deprecated with either `@Deprecated`
+		final Element deprecationDiv = fieldJavadocElement.selectFirst( ".deprecation-block" );
+		// presence of this <div/> indicates the member is deprecated
+		if ( deprecationDiv != null ) {
+			return true;
+		}
+
+		// or `@Remove`
+		final Element removeMarkerElement = fieldJavadocElement.selectFirst( "[href*=Remove.html]" );
+		if ( removeMarkerElement != null ) {
+			return true;
+		}
+
+		return false;
+	}
+
+	private static boolean interpretIncubation(Element fieldJavadocElement) {
+		final Element incubatingMarkerElement = fieldJavadocElement.selectFirst( "[href*=Incubating.html]" );
+		return incubatingMarkerElement != null;
+	}
+
 	/**
 	 * Convert the DOM representation of the field Javadoc to Asciidoc format
 	 *