From 7292e1d0018c10d7fbd4f9937c55893c205d7cad Mon Sep 17 00:00:00 2001 From: Steve Ebersole Date: Mon, 14 Aug 2023 07:49:23 -0500 Subject: [PATCH] HHH-17047 - Follow up tasks for Gradle 8.2 upgrade - toolchains - lazy Task creation - documentation (documentation/ and release/) tasks --- documentation/documentation.gradle | 2 +- .../main/java/org/hibernate/Incubating.java | 2 + .../src/main/java/org/hibernate/Internal.java | 2 + .../src/main/java/org/hibernate/Remove.java | 2 + .../orm/properties/AsciiDocWriter.java | 46 ++++++++++++++++--- .../orm/properties/SettingDescriptor.java | 16 ++++++- .../orm/properties/SettingsCollector.java | 26 ++++++++++- 7 files changed, 87 insertions(+), 9 deletions(-) diff --git a/documentation/documentation.gradle b/documentation/documentation.gradle index 0e8f20e323..8783cab174 100644 --- a/documentation/documentation.gradle +++ b/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 © 2001-$currentYear Red Hat, Inc. All Rights Reserved." diff --git a/hibernate-core/src/main/java/org/hibernate/Incubating.java b/hibernate-core/src/main/java/org/hibernate/Incubating.java index 55fc7a87e2..0a17f43d37 100644 --- a/hibernate-core/src/main/java/org/hibernate/Incubating.java +++ b/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 { } diff --git a/hibernate-core/src/main/java/org/hibernate/Internal.java b/hibernate-core/src/main/java/org/hibernate/Internal.java index ec182ba902..7c3e7601b3 100644 --- a/hibernate-core/src/main/java/org/hibernate/Internal.java +++ b/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 { } diff --git a/hibernate-core/src/main/java/org/hibernate/Remove.java b/hibernate-core/src/main/java/org/hibernate/Remove.java index 38b3ec2d24..64a2d206c7 100644 --- a/hibernate-core/src/main/java/org/hibernate/Remove.java +++ b/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 { } diff --git a/local-build-plugins/src/main/java/org/hibernate/orm/properties/AsciiDocWriter.java b/local-build-plugins/src/main/java/org/hibernate/orm/properties/AsciiDocWriter.java index 395ebea1eb..55f593c574 100644 --- a/local-build-plugins/src/main/java/org/hibernate/orm/properties/AsciiDocWriter.java +++ b/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 ); - writer.write( settingDescriptor.getName() ); - writer.write( "]] " ); + writeSettingAnchor( settingDescriptor, writer ); - writer.write( '`' ); - writer.write( settingDescriptor.getName() ); - writer.write( '`' ); + writeSettingName( settingDescriptor, writer ); 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 ); diff --git a/local-build-plugins/src/main/java/org/hibernate/orm/properties/SettingDescriptor.java b/local-build-plugins/src/main/java/org/hibernate/orm/properties/SettingDescriptor.java index 016f4d702b..5b0f85c362 100644 --- a/local-build-plugins/src/main/java/org/hibernate/orm/properties/SettingDescriptor.java +++ b/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; + } } diff --git a/local-build-plugins/src/main/java/org/hibernate/orm/properties/SettingsCollector.java b/local-build-plugins/src/main/java/org/hibernate/orm/properties/SettingsCollector.java index c4e9f13b18..706a762e0c 100644 --- a/local-build-plugins/src/main/java/org/hibernate/orm/properties/SettingsCollector.java +++ b/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
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 *