HHH-17082 - Improve documentation of configuration settings

https://hibernate.atlassian.net/browse/HHH-17082
hibernate · Aug 28, 2023 · fd961ce · fd961ce
1 parent 7dc458f
commit fd961ce
Show file tree

Hide file tree

Showing 77 changed files with 5,388 additions and 6,531 deletions.
diff --git a/documentation/documentation.gradle b/documentation/documentation.gradle
@@ -200,28 +200,34 @@ def aggregateJavadocsTask = tasks.register( "aggregateJavadocs", Javadoc ) {
 	inputs.property "ormVersion", project.ormVersion
 
 	destinationDir = mkdir( layout.buildDirectory.file( 'javadocs' ) )
-
-	source configurations.javadocSources
-	classpath += configurations.javadocClasspath
+	source = configurations.javadocSources
+	classpath = configurations.javadocClasspath
 
 	// exclude any generated sources and internal packages
 	exclude '**/generated-src/**'
 	exclude '**/internal/**'
 	include '**/*.java'
 
+	maxMemory = '512m'
 
 	final int currentYear = new GregorianCalendar().get( Calendar.YEAR )
 
-	// apply standard config
-	maxMemory = '512m'
 	configure( options ) {
-		overview = 'src/javadoc/overview.html'
-		stylesheetFile = project.file( 'src/javadoc/stylesheet.css' )
-		windowTitle = 'Hibernate JavaDocs'
-		docTitle = "Hibernate JavaDoc ($project.version)"
+		overview = 'src/main/javadoc/overview.html'
+		stylesheetFile = project.file( 'src/main/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."
 		use = true
-		options.encoding = 'UTF-8'
+		encoding = 'UTF-8'
+
+		tags(
+				'todo:X',
+				'apiNote:a:API Note:',
+				'implSpec:a:Implementation Specification:',
+				'implNote:a:Implementation Note:',
+				'settingDefault:f:Default Value:'
+		)
 
 		links = [
 				'https://docs.oracle.com/en/java/javase/11/docs/api/',
@@ -231,14 +237,14 @@ def aggregateJavadocsTask = tasks.register( "aggregateJavadocs", Javadoc ) {
 				'https://www.javadoc.io/doc/javax.cache/cache-api/1.0.0/'
 		]
 
-		options.addStringOption( 'Xdoclint:none', '-quiet' )
-
-		if ( jdkVersions.explicit ) {
-			options.setJFlags(
-					getProperty( 'toolchain.javadoc.jvmargs' ).toString().
-							split( ' ' ).toList().findAll( { !it.isEmpty() } )
-			)
-		}
+		addStringOption( 'Xdoclint:none', '-quiet' )
+//
+//		if ( jdkVersions.explicit ) {
+//			setJFlags(
+//					getProperty( 'toolchain.javadoc.jvmargs' ).toString().
+//							split( ' ' ).toList().findAll( { !it.isEmpty() } )
+//			)
+//		}
 	}
 
 	if ( jdkVersions.explicit ) {
@@ -249,6 +255,18 @@ def aggregateJavadocsTask = tasks.register( "aggregateJavadocs", Javadoc ) {
 			}
 		}
 	}
+
+	doFirst {
+		def javaLanguageVersion = javadocTool.present
+				? javadocTool.get().metadata.languageVersion
+				: JavaLanguageVersion.of( JavaVersion.current().name )
+
+		if ( javaLanguageVersion.asInt() > 11 ) {
+			println "`aggregateJavadocs` is being run with a JDK newer than version 11: \n" +
+							"\t* `stylesheet.css` will not be compatible\n" +
+							"\t* generating the User Guide settings fragment will not succeed"
+		}
+	}
 }
 
 asciidoctorj {
@@ -480,30 +498,119 @@ def renderQueryLanguageGuidesTask = tasks.register( 'renderQueryLanguageGuides'
 // User Guide ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 settingsDocumentation {
+	anchorNameBase = "settings"
 	sections {
-		core {
-			settingsClassName = "org.hibernate.cfg.AvailableSettings"
-			projectPath = ":hibernate-core"
+		compliance {
+			explicitPosition = 1
+			summary = "Jakarta Persistence Compliance Settings"
+			description = "Settings which control various aspects of compliance with the Jakarta Persistence specification "
+			settingsClassName "org.hibernate.cfg.JpaComplianceSettings"
+		}
+		persistence {
+			explicitPosition = 2
+			summary = "Persistence Unit Settings"
+			description = "Settings related to the creation and configuration of a persistence-unit - SessionFactory and EntityManagerFactory"
+			settingsClassName "org.hibernate.cfg.PersistenceSettings"
+		}
+		jdbc {
+			explicitPosition = 3
+			summary = "JDBC Settings"
+			description = "Settings which control various aspects of how Hibernate interacts with JDBC"
+			settingsClassName "org.hibernate.cfg.JdbcSettings"
+		}
+		c3p0 {
+			explicitPosition = 4
+			summary = "C3P0 Connection Pool Settings"
+			description = "Settings related to integrating with the C3P0 Connection pool"
+			settingsClassName "org.hibernate.cfg.C3p0Settings"
+		}
+		proxool {
+			explicitPosition = 5
+			summary = "Proxool Connection Pool Settings"
+			description = "Settings related to integrating with the Proxool Connection pool"
+			settingsClassName "org.hibernate.cfg.ProxoolSettings"
+		}
+		mapping {
+			explicitPosition = 6
+			summary = "Domain Mapping Settings"
+			description = "Settings which control how domain mappings are handled"
+			settingsClassName "org.hibernate.cfg.MappingSettings"
+		}
+		environment {
+			summary = "Runtime Environment Settings"
+			description = "Settings related to JNDI and ClassLoaders"
+			settingsClassName "org.hibernate.cfg.EnvironmentSettings"
+		}
+		schema {
+			summary = "Schema Tooling Settings"
+			description = "Settings which control the creation, dropping, update and validation of database schemas"
+			settingsClassName "org.hibernate.cfg.SchemaToolingSettings"
+		}
+		bytecode {
+			summary = "Bytecode Manipulation Settings"
+			description = "Settings which control Hibernate's BytecodeProvider used for bytecode manipulation"
+			settingsClassName "org.hibernate.cfg.BytecodeSettings"
+		}
+		cache {
+			summary = "Second-level Cache Settings"
+			description = "Settings which control Hibernate's second-level caching"
+			settingsClassName "org.hibernate.cfg.CacheSettings"
+			settingsClassName "org.hibernate.cache.jcache.ConfigSettings"
+		}
+		query {
+			summary = "Query Settings"
+			description = "Settings which control various parts of Hibernate's Query handling"
+			settingsClassName "org.hibernate.cfg.QuerySettings"
+		}
+		stats {
+			summary = "Statistics Settings"
+			description = "Settings which control the collection of statistics"
+			settingsClassName "org.hibernate.cfg.StatisticsSettings"
+		}
+		validation {
+			summary = "Jakarta Validation Integeration Settings"
+			description = "Settings used in the integration of Jakarta Validation"
+			settingsClassName "org.hibernate.cfg.ValidationSettings"
 		}
 		envers {
-			settingsClassName = "org.hibernate.envers.configuration.EnversSettings"
-			projectPath = ":hibernate-envers"
+			summary = "Audit/History Settings"
+			description = "Settings which control Hibernate's audit/history support (hibernate-envers)"
+			settingsClassName "org.hibernate.envers.configuration.EnversSettings"
+		}
+		spatial {
+			summary = "Hibernate Spatial Settings"
+			description = "Settings which control Hibernate's support for spatial data (hibernate-spatial)"
+			settingsClassName "org.hibernate.spatial.HibernateSpatialConfigurationSettings"
+			settingsClassName "org.hibernate.spatial.integration.SpatialService"
 		}
-		jcache {
-			settingsClassName = "org.hibernate.cache.jcache.ConfigSettings"
-			projectPath = ":hibernate-jcache"
+		misc {
+			summary = "Miscellaneous Settings"
+			description = "Miscellaneous Settings"
+			settingsClassName "org.hibernate.cfg.AvailableSettings"
 		}
 	}
 }
 
 def generateSettingsDocTask = tasks.named( "generateSettingsDoc" ) {
 	dependsOn aggregateJavadocsTask
+
+	doFirst {
+		def javadoc = aggregateJavadocsTask.get()
+		def javaLanguageVersion = javadoc.javadocTool.present
+				? javadoc.javadocTool.get().metadata.languageVersion
+				: JavaLanguageVersion.of( JavaVersion.current().name )
+
+		if ( javaLanguageVersion.asInt() > 11 ) {
+			println "`aggregateJavadocs` was run with a JDK newer than version 11; generating the settings User Guide fragment will not succeed"
+		}
+	}
 }
 
 def renderUserGuideHtmlTask = tasks.register( 'renderUserGuideHtml', AsciidoctorTask ) { task ->
 	group = "Documentation"
 	description = 'Renders the User Guides in HTML format using Asciidoctor.'
 	inputs.property "hibernate-version", project.ormVersion
+	inputs.file( generateSettingsDocTask.get().outputFile )
 
 	dependsOn generateSettingsDocTask
 

diff --git a/documentation/src/main/asciidoc/userguide/Bibliography.adoc b/documentation/src/main/asciidoc/userguide/Bibliography.adoc
@@ -1,6 +1,5 @@
-== References
-
 [bibliography]
+== References
 - [[[PoEAA]]] Martin Fowler. https://www.martinfowler.com/books/eaa.html[Patterns of Enterprise Application Architecture].
   Addison-Wesley Professional. 2002.
 - [[[JPwH]]] Christian Bauer & Gavin King. https://www.manning.com/books/java-persistence-with-hibernate-second-edition[Java Persistence with Hibernate, Second Edition]. Manning Publications Co. 2015.

diff --git a/documentation/src/main/asciidoc/userguide/ConfigPropertyList.adoc b/documentation/src/main/asciidoc/userguide/ConfigPropertyList.adoc
diff --git a/documentation/src/main/asciidoc/userguide/Hibernate_User_Guide.adoc b/documentation/src/main/asciidoc/userguide/Hibernate_User_Guide.adoc
@@ -39,17 +39,13 @@ include::chapters/beans/Beans.adoc[]
 include::chapters/portability/Portability.adoc[]
 include::chapters/statistics/Statistics.adoc[]
 include::chapters/tooling/Tooling.adoc[]
-
-include::appendices/Configurations.adoc[]
-include::appendices/Annotations.adoc[]
 include::appendices/BestPractices.adoc[]
-include::appendices/Legacy_Bootstrap.adoc[]
-include::appendices/Legacy_DomainModel.adoc[]
-include::appendices/LegacyBasicTypeResolution.adoc[]
-include::appendices/Legacy_Native_Queries.adoc[]
 
 include::Credits.adoc[]
 
-include::ConfigPropertyList.adoc[]
+include::appendices/SettingsReference.adoc[]
+include::appendices/LegacyBasicTypeResolution.adoc[]
+include::appendices/Legacy_Native_Queries.adoc[]
+
 include::Bibliography.adoc[]