THRIFT-262. java: Generate Javadocs for library classes

This patch adds a 'javadoc' Ant target, and installs the documentation to ${docdir}/thrift/java (/usr/local/share/doc/thrift/java with the default invocation of configure). It also fixes a few Javadoc warnings in the source code.

It also modifies the 'dist' target to include the Java sources in the jar file, so that Eclipse may show the javadocs for Thrift classes automatically (this increases the size of libthrift.jar from 90 Kb to 155 Kb).

git-svn-id: https://svn.apache.org/repos/asf/incubator/thrift/trunk@756603 13f79535-47bb-0310-9956-ffa450edef68

diff --git a/lib/java/Makefile.am b/lib/java/Makefile.am
index b31b0cd..9b1e84d 100644 (file)
--- a/lib/java/Makefile.am
+++ b/lib/java/Makefile.am
@@ -4,7 +4,8 @@ all-local:
        $(ANT)
 
 install-exec-hook:
-       $(ANT) install -Dinstall.path=$(DESTDIR)$(JAVA_PREFIX)
+       $(ANT) install -Dinstall.path=$(DESTDIR)$(JAVA_PREFIX) \
+               -Dinstall.javadoc.path=$(DESTDIR)$(docdir)/java
 
 # Make sure this doesn't fail if ant is not configured.
 clean-local:

diff --git a/lib/java/build.xml b/lib/java/build.xml
index 7567be4..af4af07 100644 (file)
--- a/lib/java/build.xml
+++ b/lib/java/build.xml
@@ -7,6 +7,7 @@
 
   <property name="src" location="src" />
   <property name="build" location="build" />
+  <property name="javadoc" location="${build}/javadoc" />
   <property name="install.path" value="/usr/local/lib" />
   <property name="src.test" location="test" />
   <property name="build.test" location="${build}/test" />
@@ -26,20 +27,42 @@
     <javac srcdir="${src}" destdir="${build}" source="1.5" debug="true"/>
   </target>
 
+  <target name="javadoc" depends="init">
+    <javadoc sourcepath="${src}"
+      destdir="${javadoc}"
+      version="true"
+      windowtitle="Thrift Java API"
+      doctitle="Thrift Java API">
+    </javadoc>
+  </target>
+
   <target name="dist" depends="compile">
-    <jar jarfile="libthrift.jar" basedir="${build}"/>
+    <jar jarfile="libthrift.jar">
+      <fileset dir="${build}">
+        <include name="**/*.class" />
+      </fileset>
+      <fileset dir="src">
+        <include name="**/*.java" />
+      </fileset>
+    </jar>
   </target>
 
-  <target name="install" depends="dist">
+  <target name="install" depends="dist,javadoc">
     <exec executable="install">
       <arg line="libthrift.jar ${install.path}" />
     </exec>
+    <copy todir="${install.javadoc.path}">
+      <fileset dir="${javadoc}">
+        <include name="**/*" />
+      </fileset>
+    </copy>
   </target>
 
   <target name="clean">
     <delete dir="${build}" />
     <delete dir="${gen}"/>
     <delete dir="${genbean}"/>
+    <delete dir="${javadoc}"/>
     <delete file="libthrift.jar" />
   </target>
 

diff --git a/lib/java/src/org/apache/thrift/TDeserializer.java b/lib/java/src/org/apache/thrift/TDeserializer.java
index 266906b..bbfdf21 100644 (file)
--- a/lib/java/src/org/apache/thrift/TDeserializer.java
+++ b/lib/java/src/org/apache/thrift/TDeserializer.java
@@ -68,12 +68,11 @@ public class TDeserializer {
   }
 
   /**
-   * Deerialize the Thrift object from a Java string, using the default JVM
+   * Deserialize the Thrift object from a Java string, using the default JVM
    * charset encoding.
    *
    * @param base The object to read into
    * @param data The string to read from
-   * @return Serialized object as a String
    */
   public void toString(TBase base, String data) throws TException {
     deserialize(base, data.getBytes());

diff --git a/lib/java/src/org/apache/thrift/server/THsHaServer.java b/lib/java/src/org/apache/thrift/server/THsHaServer.java
index cdca923..35f6d3c 100644 (file)
--- a/lib/java/src/org/apache/thrift/server/THsHaServer.java
+++ b/lib/java/src/org/apache/thrift/server/THsHaServer.java
@@ -190,7 +190,7 @@ public class THsHaServer extends TNonblockingServer {
     STOP_TIMEOUT_UNIT = options.stopTimeoutUnit;
   }
 
-  /** @inheritdoc */
+  /** @inheritDoc */
   @Override
   public void serve() {
     if (!startInvokerPool()) {

diff --git a/lib/java/src/org/apache/thrift/transport/TTransportFactory.java b/lib/java/src/org/apache/thrift/transport/TTransportFactory.java
index 63af5da..c9047fc 100644 (file)
--- a/lib/java/src/org/apache/thrift/transport/TTransportFactory.java
+++ b/lib/java/src/org/apache/thrift/transport/TTransportFactory.java
@@ -18,8 +18,8 @@ public class TTransportFactory {
   /**
    * Return a wrapped instance of the base Transport.
    *
-   * @param in The base transport
-   * @returns Wrapped Transport
+   * @param trans The base transport
+   * @return Wrapped Transport
    */
   public TTransport getTransport(TTransport trans) {
     return trans;