HHH-17157 - Some improvements to the metamodel generator documentation

(cherry picked from commit da522846d8)

documentation/src/main/asciidoc/userguide/chapters/tooling/gradle.adoc

@@ -60,7 +60,7 @@ It also exposes the following method forms:
 ==== Static Metamodel Generation
 
 Static metamodel generation can be incorporated into Gradle builds via the
-annotation processor provided by the `hibernate-jpamodelgen` artifact.  Applying
+annotation processor provided by the `org.hibernate.orm:hibernate-jpamodelgen` artifact.  Applying
 an annotation processor in Gradle is super easy -
 
 
@@ -70,40 +70,3 @@ dependencies {
     annotationProcessor "org.hibernate.orm:hibernate-jpamodelgen:${hibernateVersion}"
 }
 ----
-
-When the build does not need bytecode enhancement support, this is a perfectly valid solution.
-
-The plugin supports simpler configuration of the generator using the registered
-`jpaMetamodel` extension:
-
-
-[source,gradle]
-----
-hibernate {
-    jpaMetamodel {
-        applyGeneratedAnnotation false
-        suppress 'raw'
-        generationOutputDirectory "${buildDir}/generated/sources/modelgen"
-        compileOutputDirectory "${buildDir}/classes/java/modelgen"
-    }
-}
-----
-
-The extension is of type `JpaMetamodelGenerationSpec`, which exposes the following configuration properties:
-
-applyGeneratedAnnotation:: Should the `javax.annotation.processing.Generated` annotation be added to the
-generated classes.  Defaults to `true`.
-suppressions:: Suppressions to add to the generated classes.  Defaults to `['raw', 'deprecation']`
-generationOutputDirectory:: Directory where the generated metamodel classes should be created.  Defaults
-to `${buildDir}/generated/sources/jpaMetamodel`
-[[tooling-gradle-modelgen-compile-output]]
-compileOutputDirectory:: Directory where the classes compiled from the generated metamodel classes should be
-created. Defaults to `${buildDir}/classes/java/jpaMetamodel`.
-
-It also exposes the following method forms:
-
-* applyGeneratedAnnotation(boolean)
-* suppress(String)
-* generationOutputDirectory(Object)
-* compileOutputDirectory(Object)
-

documentation/src/main/asciidoc/userguide/chapters/tooling/maven.adoc

@@ -23,7 +23,8 @@ include::extras/maven-example.pom[]
 [[tooling-maven-modelgen]]
 ==== Static Metamodel Generation
 
-The recommended way to integrate the metamodel generation into a maven project is through the annotation processor paths of the maven compiler plugin (roughly equivalent to how the generator is integrated in a gradle project).
+Static metamodel generation should be integrated into a maven project through the annotation processor
+paths of the maven compiler plugin.
 
 .Integrate the metamodel generator
 ====

documentation/src/main/asciidoc/userguide/chapters/tooling/modelgen.adoc

@@ -6,31 +6,30 @@
 :example-dir-metamodelgen-generated: {testing-project-dir}/target/generated/sources/annotationProcessor/java/main/org/hibernate/testing/orm/domain/userguide
 :core-project-dir: {root-project-dir}/hibernate-core
 :toolingTestsDir: {core-project-dir}/src/test/java/org/hibernate/orm/test/tooling
+:ann-proc: https://docs.oracle.com/en/java/javase/11/tools/javac.html#GUID-082C33A5-CBCA-471A-845E-E77F79B7B049__GUID-3FA757C8-B67B-46BC-AEF9-7C3FFB126A93
+:ann-proc-path: https://docs.oracle.com/en/java/javase/11/tools/javac.html#GUID-AEEC9F07-CB49-4E96-8BC7-BCC2C7F725C9__GUID-214E175F-0F06-4CDC-B511-5BA469955F5A
+:ann-proc-options: https://docs.oracle.com/en/java/javase/11/tools/javac.html#GUID-AEEC9F07-CB49-4E96-8BC7-BCC2C7F725C9__GUID-6CC814A4-8A29-434A-B7E1-DF8234784E7C
+:intg-guide: https://docs.jboss.org/hibernate/orm/6.3/introduction/html_single/Hibernate_Introduction.html#generator
 
-Jakarta Persistence defines a typesafe Criteria API which allows `Criteria` queries to be constructed in a
+Jakarta Persistence defines a typesafe Criteria API which allows <<criteria,`Criteria`>>
-strongly-typed manner, utilizing so-called static metamodel classes.  For developers, it is important that
+queries to be constructed in a strongly-typed manner, utilizing so-called static metamodel
-the task of the metamodel generation can be automated.  Hibernate Static Metamodel Generator is an annotation
+classes.  The Hibernate Static Metamodel Generator, available via the published
-processor based on https://jcp.org/en/jsr/detail?id=269[JSR_269] with the task of creating Jakarta Persistence
+`org.hibernate.orm:hibernate-jpamodelgen` artifact, is an link:{ann-proc}[annotation processor]
-static metamodel classes.
+used to generate these static metamodel classes.
 
-See <<criteria>> for discussion of Jakarta Persistence criteria queries.
+[NOTE]
+====
+The Hibernate Static Metamodel Generator has many additional capabilities beyond static metamodel
+class generation.  See the link:{intg-guide}[Introduction Guide] for a complete discussion of its
+capabilities.  The rest of the discussion here is limited to the Jakarta Persistence static metamodel.
 
-The Hibernate Static Metamodel Generator is defined by the published `org.hibernate.orm:hibernate-jpamodelgen`
+The generator is expected to be run using the `javac` link:{ann-proc-path}[-processorpath] option.
-artifact.  As it is defined as an
+See the tool-specific discussions (<<tooling-gradle-modelgen,Gradle>>, <<tooling-maven-modelgen,Maven>>
-https://docs.oracle.com/en/java/javase/11/tools/javac.html#GUID-082C33A5-CBCA-471A-845E-E77F79B7B049[annotation processor],
-it is usable anytime `javac` is used.  See the tool-specific discussions (<<tooling-gradle-modelgen,Gradle>>, <<tooling-maven-modelgen,Maven>>
 and <<tooling-ant,Ant>>) for details on integrating the generator into those environments.
-
-NOTE:: The fully qualified name of the processor class is `org.hibernate.jpamodelgen.JPAMetaModelEntityProcessor`.
-
-[TIP]
-====
-The `javac` option _-proc:only_ instructs the compiler to just run the annotation processing.
-You can also disable annotation processing by specifying _-proc:none_.
-
-Run `'javac -help'` to see which other annotation processor relevant options can be specified.
 ====
 
+[[tooling-modelgen-classes]]
+==== Metamodel classes
 
 The structure of the metamodel classes is described in the Jakarta Persistence
 specification, but for completeness the definition is repeated in the following
@@ -108,3 +107,18 @@ include::{toolingTestsDir}/modelgen/ModelGenTests.java[tags=tooling-modelgen-usa
 ----
 ====
 
+[[tooling-modelgen-options]]
+==== Generation Options
+
+The Hibernate Static Metamodel Generator accepts a number of configuration options, which are specified as
+part of the `javac` execution using standard link:{ann-proc-options}[-A] options -
+
+`-Adebug=[true|false]`:: Enables debug logging from the generator.
+`-AfullyAnnotationConfigured=[true|false]`:: Controls whether `orm.xml` mapping should be considered.
+`-ApersistenceXml=[path]`:: Specifies the path to the `persistence.xml` file.
+`-AormXml=[path]`:: Specifies the path to an `orm.xml` file.
+`-AlazyXmlParsing=[true|false]`:: Controls whether the processor should attempt to determine whether any `orm.xml` files have changed.
+`-AaddGeneratedAnnotation=[true|false]`:: Controls whether the processor should add `@jakarta.annotation.Generated` to the generated classes.
+`-addGenerationDate=[true|false]`:: Controls whether the processor should add `@jakarta.annotation.Generated#date`.
+`-addSuppressWarningsAnnotation=[true|false]`:: Controls whether the processor should add `@SuppressWarnings({"deprecation","rawtypes"})` to the generated classes.
+

tooling/metamodel-generator/src/main/java/org/hibernate/jpamodelgen/JPAMetaModelEntityProcessor.java

@@ -83,13 +83,46 @@ import static org.hibernate.jpamodelgen.util.TypeUtils.toTypeString;
 		JPAMetaModelEntityProcessor.ADD_SUPPRESS_WARNINGS_ANNOTATION
 })
 public class JPAMetaModelEntityProcessor extends AbstractProcessor {
+	/**
+	 * Debug logging from the processor
+	 */
 	public static final String DEBUG_OPTION = "debug";
+
+	/**
+	 * Path to a {@code persistence.xml} file
+	 */
 	public static final String PERSISTENCE_XML_OPTION = "persistenceXml";
+
+	/**
+	 * Path to an {@code orm.xml} file
+	 */
 	public static final String ORM_XML_OPTION = "ormXml";
+
+	/**
+	 * Controls whether the processor should consider XML files
+	 */
 	public static final String FULLY_ANNOTATION_CONFIGURED_OPTION = "fullyAnnotationConfigured";
+
+	/**
+	 * Controls whether the processor should only load XML files when there have been changes
+	 */
 	public static final String LAZY_XML_PARSING = "lazyXmlParsing";
-	public static final String ADD_GENERATION_DATE = "addGenerationDate";
+
+	/**
+	 * Whether the {@code jakarta.annotation.Generated} annotation should be added to
+	 * the generated classes
+	 */
 	public static final String ADD_GENERATED_ANNOTATION = "addGeneratedAnnotation";
+
+	/**
+	 * Assuming that {@linkplain #ADD_GENERATED_ANNOTATION} is enabled, this option controls
+	 * whether {@code @Generated#date} should be populated.
+	 */
+	public static final String ADD_GENERATION_DATE = "addGenerationDate";
+
+	/**
+	 * Controls whether {@code @SuppressWarnings({"deprecation","rawtypes"})} should be added to the generated classes
+	 */
 	public static final String ADD_SUPPRESS_WARNINGS_ANNOTATION = "addSuppressWarningsAnnotation";
 
 	private static final boolean ALLOW_OTHER_PROCESSORS_TO_CLAIM_ANNOTATIONS = false;