From aa78ebbd5a589efbf979e63e0a7e35f0e410f350 Mon Sep 17 00:00:00 2001
From: Misty Stanley-Jones <mstanleyjones@cloudera.com>
Date: Fri, 16 Oct 2015 23:37:20 +1000
Subject: [PATCH] Lots of work on the POM to enhance Javadocs, Xrefs

* We now have apidocs, devapidocs, testapidocs, and testdevapidocs
* When using reportSets, the Javadoc plugin ignores the plugin configuration,
  so I propagated it to the individual reportSet configuration blocks.
* I was able to remove some of the logic that moved / copied things around
  in post-site.
* We now have xref and xref-test (these are superfluous but something needs them
  so I left them)
* Added source to Javadocs -- you can click a method or property to browse its source.
  More user-friendly than xref maybe.
* You can now get the whole site to build by doing 'mvn clean site site:stage' and
  it takes about 10 minutes.
---
 .../apache/hadoop/hbase/HTableDescriptor.java |   6 +-
 pom.xml                                       | 238 +++++++++++++-----
 src/main/site/site.xml                        |  38 ++-
 3 files changed, 203 insertions(+), 79 deletions(-)

diff --git a/hbase-client/src/main/java/org/apache/hadoop/hbase/HTableDescriptor.java b/hbase-client/src/main/java/org/apache/hadoop/hbase/HTableDescriptor.java
index 28d125d4b44..f3d7312ed56 100644
--- a/hbase-client/src/main/java/org/apache/hadoop/hbase/HTableDescriptor.java
+++ b/hbase-client/src/main/java/org/apache/hadoop/hbase/HTableDescriptor.java
@@ -320,7 +320,7 @@ public class HTableDescriptor implements Comparable<HTableDescriptor> {
   /**
    * Construct a table descriptor specifying a TableName object
    * @param name Table name.
-   * @see <a href="HADOOP-1581">HADOOP-1581 HBASE: Un-openable tablename bug</a>
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-174">HADOOP-1581 HBASE: (HBASE-174) Un-openable tablename bug</a>
    */
   public HTableDescriptor(final TableName name) {
     super();
@@ -330,7 +330,7 @@ public class HTableDescriptor implements Comparable<HTableDescriptor> {
   /**
    * Construct a table descriptor specifying a byte array table name
    * @param name Table name.
-   * @see <a href="HADOOP-1581">HADOOP-1581 HBASE: Un-openable tablename bug</a>
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-174">HADOOP-1581 (HBASE-174) HBASE: Un-openable tablename bug</a>
    */
   @Deprecated
   public HTableDescriptor(final byte[] name) {
@@ -340,7 +340,7 @@ public class HTableDescriptor implements Comparable<HTableDescriptor> {
   /**
    * Construct a table descriptor specifying a String table name
    * @param name Table name.
-   * @see <a href="HADOOP-1581">HADOOP-1581 HBASE: Un-openable tablename bug</a>
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-174">HADOOP-1581 (HBASE-174) HBASE: Un-openable tablename bug</a>
    */
   @Deprecated
   public HTableDescriptor(final String name) {
diff --git a/pom.xml b/pom.xml
index 256a2ed945c..e5053996175 100644
--- a/pom.xml
+++ b/pom.xml
@@ -970,24 +970,6 @@
         <!--$NO-MVN-MAN-VER$ -->
         <inherited>false</inherited>
         <executions>
-          <execution>
-            <id>copy-javadocs</id>
-            <goals>
-              <goal>copy-resources</goal>
-            </goals>
-            <phase>site</phase>
-            <configuration>
-              <outputDirectory>target/site/apidocs</outputDirectory>
-              <resources>
-                <resource>
-                  <directory>${basedir}/target/apidocs</directory>
-                  <includes>
-                    <include>**/**</include>
-                  </includes>
-                </resource>
-              </resources>
-            </configuration>
-          </execution>
           <execution>
             <id>copy-htaccess</id>
             <goals>
@@ -995,7 +977,7 @@
             </goals>
             <phase>post-site</phase>
             <configuration>
-              <outputDirectory>${basedir}/target/site</outputDirectory>
+              <outputDirectory>${project.reporting.outputDirectory}/</outputDirectory>
               <resources>
                 <resource>
                   <directory>${basedir}/src/main/site/resources/</directory>
@@ -1014,7 +996,7 @@
             </goals>
             <phase>post-site</phase>
             <configuration>
-              <outputDirectory>${basedir}/target/site</outputDirectory>
+              <outputDirectory>${project.reporting.outputDirectory}/</outputDirectory>
               <resources>
                 <resource>
                   <directory>${basedir}/src/main/site/resources/</directory>
@@ -1075,7 +1057,7 @@
           </dependency>
         </dependencies>
         <configuration>
-          <outputDirectory>target/site</outputDirectory>
+          <outputDirectory>${project.reporting.outputDirectory}/</outputDirectory>
           <doctype>book</doctype>
           <imagesDir>images</imagesDir>
           <sourceHighlighter>coderay</sourceHighlighter>
@@ -1127,8 +1109,8 @@
             <phase>post-site</phase>
             <configuration>
               <target name="rename file">
-                <move file="${project.basedir}/target/site/book.pdf" tofile="${project.basedir}/target/site/apache_hbase_reference_guide.pdf" />
-                <move file="${project.basedir}/target/site/book.pdfmarks" tofile="${project.basedir}/target/site/apache_hbase_reference_guide.pdfmarks" />
+                <move file="${project.reporting.outputDirectory}/book.pdf" tofile="${project.reporting.outputDirectory}/apache_hbase_reference_guide.pdf" />
+                <move file="${project.reporting.outputDirectory}/book.pdfmarks" tofile="${project.reporting.outputDirectory}/apache_hbase_reference_guide.pdfmarks" />
               </target>
             </configuration>
             <goals>
@@ -2764,37 +2746,25 @@
       <plugin>
         <artifactId>maven-project-info-reports-plugin</artifactId>
         <version>2.7</version>
-        <reportSets>
-          <reportSet>
-            <reports>
-              <report>project-team</report>
-              <report>mailing-list</report>
-              <report>cim</report>
-              <report>issue-tracking</report>
-              <report>license</report>
-              <report>scm</report>
-              <report>index</report>
-            </reports>
-          </reportSet>
-        </reportSets>
+        <!-- see src/main/site/site.xml for selected reports -->
         <configuration>
           <dependencyLocationsEnabled>false</dependencyLocationsEnabled>
         </configuration>
       </plugin>
 
+      <!-- This seems to be needed by the surefire plugin.
+           The Javadoc below provide code as well -->
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-jxr-plugin</artifactId>
         <version>2.3</version>
         <configuration>
           <aggregate>true</aggregate>
+          <test-aggregate>true</test-aggregate>
           <linkJavadoc>true</linkJavadoc>
-          <javadocDir>${basedir}/target/site/apidocs</javadocDir>
-          <reportOutputDirectory>${basedir}/target/site/xref</reportOutputDirectory>
-          <destDir>${basedir}/target/site/xref</destDir>
-          <excludes>
-            <exclude>**/generated/**</exclude>
-          </excludes>
+          <javadocDir>${project.reporting.outputDirectory}/devapidocs</javadocDir>
+          <testJavadocDir>${project.reporting.outputDirectory}/testdevapidocs</testJavadocDir>
+          <destDir>${project.reporting.outputDirectory}/xref</destDir>
         </configuration>
       </plugin>
 
@@ -2802,36 +2772,87 @@
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-javadoc-plugin</artifactId>
         <version>2.10.3</version>
-        <configuration>
-          <sourceFilesExclude>**/generated</sourceFilesExclude>
-          <excludePackageNames>org.apache.hadoop.hbase.generated.master:org.apache.hadoop.hbase.protobuf.generated</excludePackageNames>
-          <maxmemory>2048m</maxmemory>
-          <notimestamp>true</notimestamp>
-          <!-- JDK8 javadoc requires test scope transitive dependencies due to our custom doclet -->
-          <additionalDependencies>
-            <additionalDependency>
-              <groupId>org.mockito</groupId>
-              <artifactId>mockito-all</artifactId>
-              <version>${mockito-all.version}</version>
-            </additionalDependency>
-            <additionalDependency>
-              <groupId>org.hamcrest</groupId>
-              <artifactId>hamcrest-core</artifactId>
-              <version>${hamcrest.version}</version>
-            </additionalDependency>
-          </additionalDependencies>
-        </configuration>
         <reportSets>
+          <!-- Dev API -->
           <reportSet>
             <id>devapi</id>
             <reports>
               <report>aggregate</report>
+              <report>test-aggregate</report>
             </reports>
             <configuration>
               <destDir>devapidocs</destDir>
+              <name>Developer API</name>
+              <description>The full HBase API, including private and unstable APIs</description>
+              <sourceFilesExclude>**/generated/*</sourceFilesExclude>
+              <excludePackageNames>org.apache.hadoop.hbase.generated.master:org.apache.hadoop.hbase.protobuf.generated:org.apache.hadoop.hbase.tmpl.common</excludePackageNames>
+              <quiet>true</quiet>
+              <linksource>true</linksource>
+              <sourcetab>2</sourcetab>
+              <validateLinks>true</validateLinks>
+              <fixClassComment>true</fixClassComment>
+              <fixFieldComment>true</fixFieldComment>
+              <fixMethodComment>true</fixMethodComment>
+              <fixTags>all</fixTags>
+              <notimestamp>true</notimestamp>
+              <!-- Pass some options straight to the javadoc executable since it is easier -->
+              <additionalJOption>-J-Xmx2G</additionalJOption>
+              <!-- JDK8 javadoc requires test scope transitive dependencies due to our custom doclet -->
+              <additionalDependencies>
+                <additionalDependency>
+                  <groupId>org.mockito</groupId>
+                  <artifactId>mockito-all</artifactId>
+                  <version>${mockito-all.version}</version>
+                </additionalDependency>
+                <additionalDependency>
+                  <groupId>org.hamcrest</groupId>
+                  <artifactId>hamcrest-core</artifactId>
+                  <version>${hamcrest.version}</version>
+                </additionalDependency>
+              </additionalDependencies>
+              <inherited>false</inherited>
+            </configuration>
+          </reportSet>
+          <reportSet>
+            <id>testdevapi</id>
+            <reports>
+              <report>test-aggregate</report>
+            </reports>
+            <configuration>
+              <destDir>testdevapidocs</destDir>
+              <name>Developer API</name>
+              <description>The full HBase API, including private and unstable APIs</description>
+              <sourceFilesExclude>**/generated/*</sourceFilesExclude>
+              <excludePackageNames>org.apache.hadoop.hbase.generated.master:org.apache.hadoop.hbase.protobuf.generated:org.apache.hadoop.hbase.tmpl.common</excludePackageNames>
+              <quiet>true</quiet>
+              <linksource>true</linksource>
+              <sourcetab>2</sourcetab>
+              <validateLinks>true</validateLinks>
+              <fixClassComment>true</fixClassComment>
+              <fixFieldComment>true</fixFieldComment>
+              <fixMethodComment>true</fixMethodComment>
+              <fixTags>all</fixTags>
+              <notimestamp>true</notimestamp>
+              <!-- Pass some options straight to the javadoc executable since it is easier -->
+              <additionalJOption>-J-Xmx2G</additionalJOption>
+              <!-- JDK8 javadoc requires test scope transitive dependencies due to our custom doclet -->
+              <additionalDependencies>
+                <additionalDependency>
+                  <groupId>org.mockito</groupId>
+                  <artifactId>mockito-all</artifactId>
+                  <version>${mockito-all.version}</version>
+                </additionalDependency>
+                <additionalDependency>
+                  <groupId>org.hamcrest</groupId>
+                  <artifactId>hamcrest-core</artifactId>
+                  <version>${hamcrest.version}</version>
+                </additionalDependency>
+              </additionalDependencies>
+              <inherited>false</inherited>
             </configuration>
           </reportSet>
 
+          <!-- User API -->
           <reportSet>
             <id>userapi</id>
             <reports>
@@ -2846,6 +2867,7 @@
                 <artifactId>hbase-annotations</artifactId>
                 <version>${project.version}</version>
               </docletArtifact>
+              <useStandardDocletOptions>true</useStandardDocletOptions>
               <destDir>apidocs</destDir>
               <name>User API</name>
               <description>The HBase Application Programmer's API</description>
@@ -2854,15 +2876,104 @@
               </excludePackageNames>
               <!-- switch on dependency-driven aggregation -->
               <includeDependencySources>false</includeDependencySources>
-
               <dependencySourceIncludes>
                 <!-- include ONLY dependencies I control -->
                 <dependencySourceInclude>org.apache.hbase:hbase-annotations</dependencySourceInclude>
-             </dependencySourceIncludes>
+              </dependencySourceIncludes>
+              <outputDirectory>${project.reporting.outputDirectory}/devapidocs</outputDirectory>
+              <name>Developer API</name>
+              <description>The full HBase API, including private and unstable APIs</description>
+              <sourceFilesExclude>**/generated/*</sourceFilesExclude>
+              <excludePackageNames>org.apache.hadoop.hbase.generated.master:org.apache.hadoop.hbase.protobuf.generated:org.apache.hadoop.hbase.tmpl.common</excludePackageNames>
+              <quiet>true</quiet>
+              <linksource>true</linksource>
+              <sourcetab>2</sourcetab>
+              <validateLinks>true</validateLinks>
+              <fixClassComment>true</fixClassComment>
+              <fixFieldComment>true</fixFieldComment>
+              <fixMethodComment>true</fixMethodComment>
+              <fixTags>all</fixTags>
+              <notimestamp>true</notimestamp>
+              <!-- Pass some options straight to the javadoc executable since it is easier -->
+              <additionalJOption>-J-Xmx2G</additionalJOption>
+              <!-- JDK8 javadoc requires test scope transitive dependencies due to our custom doclet -->
+              <additionalDependencies>
+                <additionalDependency>
+                  <groupId>org.mockito</groupId>
+                  <artifactId>mockito-all</artifactId>
+                  <version>${mockito-all.version}</version>
+                </additionalDependency>
+                <additionalDependency>
+                  <groupId>org.hamcrest</groupId>
+                  <artifactId>hamcrest-core</artifactId>
+                  <version>${hamcrest.version}</version>
+                </additionalDependency>
+              </additionalDependencies>
+              <inherited>false</inherited>
+            </configuration>
+          </reportSet>
+          <reportSet>
+            <id>testuserapi</id>
+            <reports>
+              <report>test-aggregate</report>
+            </reports>
+            <configuration>
+              <doclet>
+                org.apache.hadoop.hbase.classification.tools.IncludePublicAnnotationsStandardDoclet
+              </doclet>
+              <docletArtifact>
+                <groupId>org.apache.hbase</groupId>
+                <artifactId>hbase-annotations</artifactId>
+                <version>${project.version}</version>
+              </docletArtifact>
+              <useStandardDocletOptions>true</useStandardDocletOptions>
+              <destDir>testapidocs</destDir>
+              <name>User API</name>
+              <description>The HBase Application Programmer's API</description>
+              <excludePackageNames>
+                org.apache.hadoop.hbase.backup*:org.apache.hadoop.hbase.catalog:org.apache.hadoop.hbase.client.coprocessor:org.apache.hadoop.hbase.client.metrics:org.apache.hadoop.hbase.codec*:org.apache.hadoop.hbase.constraint:org.apache.hadoop.hbase.coprocessor.*:org.apache.hadoop.hbase.executor:org.apache.hadoop.hbase.fs:*.generated.*:org.apache.hadoop.hbase.io.hfile.*:org.apache.hadoop.hbase.mapreduce.hadoopbackport:org.apache.hadoop.hbase.mapreduce.replication:org.apache.hadoop.hbase.master.*:org.apache.hadoop.hbase.metrics*:org.apache.hadoop.hbase.migration:org.apache.hadoop.hbase.monitoring:org.apache.hadoop.hbase.p*:org.apache.hadoop.hbase.regionserver.compactions:org.apache.hadoop.hbase.regionserver.handler:org.apache.hadoop.hbase.regionserver.snapshot:org.apache.hadoop.hbase.replication.*:org.apache.hadoop.hbase.rest.filter:org.apache.hadoop.hbase.rest.model:org.apache.hadoop.hbase.rest.p*:org.apache.hadoop.hbase.security.*:org.apache.hadoop.hbase.thrift*:org.apache.hadoop.hbase.tmpl.*:org.apache.hadoop.hbase.tool:org.apache.hadoop.hbase.trace:org.apache.hadoop.hbase.util.byterange*:org.apache.hadoop.hbase.util.test:org.apache.hadoop.hbase.util.vint:org.apache.hadoop.hbase.zookeeper.lock:org.apache.hadoop.metrics2*
+              </excludePackageNames>
+              <!-- switch on dependency-driven aggregation -->
+              <includeDependencySources>false</includeDependencySources>
+              <dependencySourceIncludes>
+                <!-- include ONLY dependencies I control -->
+                <dependencySourceInclude>org.apache.hbase:hbase-annotations</dependencySourceInclude>
+              </dependencySourceIncludes>
+              <outputDirectory>${project.reporting.outputDirectory}/devapidocs</outputDirectory>
+              <name>Developer API</name>
+              <description>The full HBase API, including private and unstable APIs</description>
+              <sourceFilesExclude>**/generated/*</sourceFilesExclude>
+              <excludePackageNames>org.apache.hadoop.hbase.generated.master:org.apache.hadoop.hbase.protobuf.generated:org.apache.hadoop.hbase.tmpl.common</excludePackageNames>
+              <quiet>true</quiet>
+              <linksource>true</linksource>
+              <sourcetab>2</sourcetab>
+              <validateLinks>true</validateLinks>
+              <fixClassComment>true</fixClassComment>
+              <fixFieldComment>true</fixFieldComment>
+              <fixMethodComment>true</fixMethodComment>
+              <fixTags>all</fixTags>
+              <notimestamp>true</notimestamp>
+              <!-- Pass some options straight to the javadoc executable since it is easier -->
+              <additionalJOption>-J-Xmx2G</additionalJOption>
+              <!-- JDK8 javadoc requires test scope transitive dependencies due to our custom doclet -->
+              <additionalDependencies>
+                <additionalDependency>
+                  <groupId>org.mockito</groupId>
+                  <artifactId>mockito-all</artifactId>
+                  <version>${mockito-all.version}</version>
+                </additionalDependency>
+                <additionalDependency>
+                  <groupId>org.hamcrest</groupId>
+                  <artifactId>hamcrest-core</artifactId>
+                  <version>${hamcrest.version}</version>
+                </additionalDependency>
+              </additionalDependencies>
+              <inherited>false</inherited>
             </configuration>
           </reportSet>
         </reportSets>
       </plugin>
+
       <plugin>
         <groupId>org.apache.maven.plugins</groupId>
         <artifactId>maven-checkstyle-plugin</artifactId>
@@ -2873,6 +2984,7 @@
           <suppressionsLocation>hbase/checkstyle-suppressions.xml</suppressionsLocation>
         </configuration>
       </plugin>
+
     </plugins>
   </reporting>
   <distributionManagement>
diff --git a/src/main/site/site.xml b/src/main/site/site.xml
index 9f7ddf78ff6..2364889900f 100644
--- a/src/main/site/site.xml
+++ b/src/main/site/site.xml
@@ -51,28 +51,29 @@
   <body>
     <menu name="Apache HBase Project">
       <item name="Overview" href="index.html"/>
-      <item name="License" href="license.html" />
-      <item name="Downloads" href="http://www.apache.org/dyn/closer.cgi/hbase/" />
+      <item name="License" href="license.html"/>
+      <item name="Downloads" href="http://www.apache.org/dyn/closer.cgi/hbase/"/>
       <item name="Release Notes" href="https://issues.apache.org/jira/browse/HBASE?report=com.atlassian.jira.plugin.system.project:changelog-panel#selectedTab=com.atlassian.jira.plugin.system.project%3Achangelog-panel" />
-      <item name="Code Of Conduct" href="coc.html" />
-      <item name="Issue Tracking" href="issue-tracking.html" />
-      <item name="Mailing Lists" href="mail-lists.html" />
-      <item name="Source Repository" href="source-repository.html" />
+      <item name="Code Of Conduct" href="coc.html"/>
+      <item name="Issue Tracking" href="issue-tracking.html"/>
+      <item name="Mailing Lists" href="mail-lists.html"/>
+      <item name="Blog" href="http://blogs.apache.org/hbase/"/>
+      <item name="Team" href="team-list.html"/>
       <item name="ReviewBoard" href="https://reviews.apache.org"/>
-      <item name="Team" href="team-list.html" />
-      <item name="Thanks" href="sponsors.html" />
-      <item name="Blog" href="http://blogs.apache.org/hbase/" />
-      <item name="Powered by HBase" href="poweredbyhbase.html" />
-      <item name="Supporting Projects" href="supportingprojects.html" />
-      <item name="Other resources" href="resources.html" />
+      <item name="Thanks" href="sponsors.html"/>
+      <item name="Powered by HBase" href="poweredbyhbase.html"/>
+      <item name="Other resources" href="resources.html"/>
     </menu>
-    <menu name="Documentation">
+    <menu name="Documentation and API">
       <item name="Reference Guide" href="book.html" target="_blank" />
       <item name="Reference Guide (PDF)" href="apache_hbase_reference_guide.pdf" target="_blank" />
       <item name="Getting Started" href="book.html#quickstart" target="_blank" />
       <item name="User API" href="apidocs/index.html" target="_blank" />
+      <item name="User API (Test)" href="testapidocs/index.html" target="_blank" />
       <item name="Developer API" href="devapidocs/index.html" target="_blank" />
+      <item name="Developer API (Test)" href="testdevapidocs/index.html" target="_blank" />
       <item name="X-Ref" href="xref/index.html" />
+      <item name="X-Ref (Test)" href="xref-test/index.html" />
       <item name="中文参考指南(单页)" href="http://abloz.com/hbase/book.html" target="_blank" />
       <item name="FAQ" href="book.html#faq" target="_blank" />
       <item name="Videos/Presentations" href="book.html#other.info" target="_blank" />
@@ -88,6 +89,17 @@
       <item name="X-Ref" href="0.94/xref/index.html" target="_blank" />
       <item name="Ref Guide (single-page)" href="0.94/book.html" target="_blank" />
     </menu>
+    <menu name="Project Reports">
+      <item name="Continuous Integration" href="integration.html"/>
+      <item name="Dependencies" href="dependency-info.html"/>
+      <item name="Dependency Convergence" href="dependency-convergence.html"/>
+      <item name="Dependency Management" href="dependency-management.html"/>
+      <item name="Distribution Management" href="distribution-management.html"/>
+      <item name="Modules" href="modules.html"/>
+      <item name="Plugin Management" href="plugin-management.html"/>
+      <item name="Plugins" href="plugins.html"/>
+      <item name="Source Repository" href="source-repository.html"/>
+    </menu>
     <menu name="ASF">
       <item name="Apache Software Foundation" href="http://www.apache.org/foundation/" target="_blank" />
       <item name="How Apache Works" href="http://www.apache.org/foundation/how-it-works.html" target="_blank" />