HHH-6782 - define javadoc groups based on api/spi/internal

release/release.gradle

@@ -13,10 +13,45 @@ ideaModule {
 javadocBuildDir = dir( buildDirName + "/documentation/javadocs" )
 
 def List subProjectsToSkipForJavadoc = ['release','documentation'];
+def List sourceSetsToSkipForJavadoc = ['test','matrix'];
 
 def copyRightYear = new java.util.GregorianCalendar().get( java.util.Calendar.YEAR );
 
 task aggregateJavadocs(type: Javadoc) {
+    Set<String> apiPackages = new HashSet<String>()
+    Set<String> spiPackages = new HashSet<String>()
+    Set<String> internalPackages = new HashSet<String>()
+
+    parent.subprojects.each{ subProject->
+        if ( !subProjectsToSkipForJavadoc.contains( subProject.name ) ) {
+            subProject.sourceSets.each { sourceSet ->
+                if ( !sourceSetsToSkipForJavadoc.contains( sourceSet.name ) ) {
+                    source sourceSet.java
+
+                    if( classpath ) {
+                        classpath += sourceSet.classes + sourceSet.compileClasspath
+                    }
+                    else {
+                        classpath = sourceSet.classes + sourceSet.compileClasspath
+                    }
+
+                    sourceSet.java.each { javaFile ->
+                        final String packageName = determinePackageName( sourceSet.java, javaFile );
+                        if ( packageName.endsWith( ".internal" ) || packageName.contains( ".internal." ) ) {
+                            internalPackages.add( packageName );
+                        }
+                        else if ( packageName.endsWith( ".spi" ) || packageName.contains( ".spi." ) ) {
+                            spiPackages.add( packageName );
+                        }
+                        else {
+                            apiPackages.add( packageName );
+                        }
+                    }
+                }
+            }
+        }
+    }
+
     description = "Build the aggregated JavaDocs for all modules"
     maxMemory = '512m'
     destinationDir = javadocBuildDir.dir
@@ -28,70 +63,26 @@ task aggregateJavadocs(type: Javadoc) {
         bottom = "Copyright &copy; 2001-$copyRightYear <a href=\"http://redhat.com\">Red Hat, Inc.</a>  All Rights Reserved."
         use = true
         links = [ 'http://download.oracle.com/javase/6/docs/api/', 'http://download.oracle.com/javaee/6/api/' ]
-        group(
+        group( 'API', apiPackages.asList() )
-            'Core API', [
+        group( 'SPI', spiPackages.asList() )
-                'org.hibernate',
+        group( 'Internal', internalPackages.asList() )
-                'org.hibernate.classic',
+        group ( 'Testing Support', ['org.hibernate.testing*'] )
-                'org.hibernate.criterion',
-                'org.hibernate.mapping',
-                'org.hibernate.metadata',
-                'org.hibernate.cfg',
-                'org.hibernate.stat'
-            ]
-        )
-        group(
-            'Extension SPI', [
-                'org.hibernate.id*',
-                'org.hibernate.connection',
-                'org.hibernate.transaction',
-                'org.hibernate.type',
-                'org.hibernate.dialect*',
-                'org.hibernate.cache*',
-                'org.hibernate.event*',
-                'org.hibernate.property',
-                'org.hibernate.loader*',
-                'org.hibernate.persister*',
-                'org.hibernate.proxy',
-                'org.hibernate.tuple',
-                'org.hibernate.transform',
-                'org.hibernate.collection',
-                'org.hibernate.jdbc',
-                'org.hibernate.usertype'
-            ]
-        )
-        group(
-            'Bytecode providers', [
-                 'org.hibernate.bytecode*',
-                 'org.hibernate.intercept*'
-            ]
-        )
-        group (
-            'Infinispan Integration', ['org.hibernate.cache.infinispan*']
-        )
-        group (
-            'JBossCache Integration', ['org.hibernate.cache.jbc*']
-        )
-        group (
-            'Testing Support', ['org.hibernate.junit*']
-        )
     }
+}
 
-    parent.subprojects.each{ subProject->
+String determinePackageName(SourceDirectorySet sourceDirectorySet, File javaFile) {
-        if ( !subProjectsToSkipForJavadoc.contains( subProject.name ) ) {
+    final javaFileAbsolutePath = javaFile.absolutePath;
-            subProject.sourceSets.each { set ->
+    for ( File sourceDirectory : sourceDirectorySet.srcDirs ) {
-                if ( !"test".equals( set.name ) ) {
+        final String sourceDirectoryAbsolutePath = sourceDirectory.absolutePath;
-                    source set.java
+        if ( javaFileAbsolutePath.startsWith( sourceDirectoryAbsolutePath ) ) {
-
+            final String javaFileRelativePath = javaFileAbsolutePath.substring(
-                    if( classpath ) {
+                    sourceDirectoryAbsolutePath.length() + 1,
-                        classpath += set.classes + set.compileClasspath
+                    javaFileAbsolutePath.lastIndexOf( '/' )
-                    }
+            );
-                    else {
+            return javaFileRelativePath.replace( '/', '.' );
-                        classpath = set.classes + set.compileClasspath
-                    }
-                }
-            }
         }
     }
+    throw new RuntimeException( "ugh" );
 }
 
 aggregateJavadocs.doLast {

release/src/javadoc/package.html

@@ -27,20 +27,21 @@
 
 Hibernate provides both<ul>
     <li>
-        a native API comprised mainly of {@link org.hibernate.SessionFactory} and {@link org.hibernate.Session}
+        a native API comprised centrally around {@link org.hibernate.SessionFactory} and {@link org.hibernate.Session}
     </li>
     <li>
-        an implementation of the <a href="">JSR-317</a> Java Persistence API (JPA) specification comprised mainly of
+        an implementation of the <a href="http://jcp.org/en/jsr/detail?id=317">JSR-317</a> Java Persistence API (JPA)
-        {@link org.hibernate.ejb.EntityManagerFactoryImpl} and {@link org.hibernate.ejb.EntityManagerImpl}
+        specification comprised centrally around {@link org.hibernate.ejb.EntityManagerFactoryImpl} and
+        {@link org.hibernate.ejb.EntityManagerImpl} (the Hibernate implementations of
+        {@link javax.persistence.EntityManager} and{@link javax.persistence.EntityManagerFactory}, respectively)
     </li>
 </ul>
 <hr/>
 
 <h3>Native API</h3>
-In addition to  {@link org.hibernate.SessionFactory} and {@link org.hibernate.Session}, applications using the
+In addition to SessionFactory and Session, applications using the native API will often utilize the following
-native API will often need to utilize the following interfaces:<ul>
+interfaces:<ul>
     <li>{@link org.hibernate.cfg.Configuration}</li>
-    <li>{@link org.hibernate.Hibernate}</li>
     <li>{@link org.hibernate.Transaction}</li>
     <li>{@link org.hibernate.Query}</li>
     <li>{@link org.hibernate.Criteria}</li>
@@ -58,36 +59,23 @@ These interfaces are fully intended to be exposed to application code.
 The JPA interfaces are all defined by the JPA specification.  For details see {@link javax.persistence}
 <hr/>
 
-<h3>Extensions</h3>
+<h3>Package Groups</h3>
-Hibernate defines a number of interfaces that are completely intended to be extendable by application programmers and/or
+This documentation groups packages into the following 3 categories:<ul>
-integrators.  Listed below is a (not necessarily exhaustive) list of the most commonly utilized extension points:<ul>
+    <li>
-    <li>{@link org.hibernate.EntityNameResolver}</li>
+        <strong>API</strong> - classes to which application code will generally bind directly.
-    <li>{@link org.hibernate.Interceptor} / {@link org.hibernate.EmptyInterceptor}</li>
+    </li>
-    <li>{@link org.hibernate.Transaction} / {@link org.hibernate.transaction.TransactionFactory}</li>
+    <li>
-    <li>{@link org.hibernate.context.CurrentSessionContext}</li>
+        <strong>SPI</strong> - classes to which application developers or integrators will commonly bind directly in
-    <li>{@link org.hibernate.dialect.Dialect}</li>
+        order to develop extensions to Hibernate, or to alter its behavior in some way.
-    <li>{@link org.hibernate.dialect.resolver.DialectResolver}</li>
+    </li>
-    <li>{@link org.hibernate.event event listener} interfaces</li>
+    <li>
-    <li>{@link org.hibernate.id.IdentifierGenerator}</li>
+        <strong>Internal</strong> - classes which are intended only to be used by Hibernate.  Use of these classes
-    <li>{@link org.hibernate.tuple.entity.EntityTuplizer} / {@link org.hibernate.tuple.component.ComponentTuplizer}</li>
+        outside of Hibernate specific use cases is not supported.  Moreover, these contracts can change frequently
-    <li>{@link org.hibernate.type.Type} / {@link org.hibernate.usertype}</li>
+        between releases whereas APIs and SPIs are more stable.
+    </li>
 </ul>
-Note that there is a large degree of crossover between the notion of extension points and that of an integration SPI (below).
 <hr/>
 
-<h3>Integration SPI</h3>
+Complete Hibernate documentation may be found online at <a href="http://docs.jboss.org/hibernate/">http://docs.jboss.org/hibernate/</a>
-Hibernate provides a number of SPIs intended to integrate itself with various third party frameworks or application code to provide
-additional capabilities.   The SPIs fall mainly into 2 categories:<ul>
-    <li>Caching - {@link org.hibernate.cache.RegionFactory}</li>
-    <li>JDBC Connection management - {@link org.hibernate.connection.ConnectionProvider}
-</ul>
-Certainly {@link org.hibernate.dialect.Dialect} could fit in here as well, though we chose to list it under extensions since application
-developers tend to provide extended dialects rather frequently for various reasons.
-<br/>
-Another SPI that is not yet exposed but is planned for such is the <em>bytecode provider</em> SPI.  See {@link org.hibernate.bytecode}
-for details.
-<hr/>
-
-Complete Hibernate documentation may be found online at <a href="http://docs.jboss.org/hibernate/">http://docs.jboss.org/hibernate/</a>.
 
 </body>