HBASE-14603 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.
This commit is contained in:
Misty Stanley-Jones 2015-10-16 23:37:20 +10:00
parent 74d5232065
commit 2996355e94
3 changed files with 202 additions and 66 deletions

View File

@ -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) {

224
pom.xml
View File

@ -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>
@ -2775,19 +2757,19 @@
</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>
@ -2795,36 +2777,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>
@ -2839,6 +2872,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>
@ -2847,15 +2881,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>
@ -2866,6 +2989,7 @@
<suppressionsLocation>hbase/checkstyle-suppressions.xml</suppressionsLocation>
</configuration>
</plugin>
</plugins>
</reporting>
<distributionManagement>

View File

@ -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" />