From 32e04b423d01e3d37ab72685407313da6a4416f6 Mon Sep 17 00:00:00 2001
From: Bryan Duxbury <bryanduxbury@apache.org>
Date: Fri, 20 Mar 2009 16:43:06 +0000
Subject: [PATCH] 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
---
 lib/java/Makefile.am                          |  3 ++-
 lib/java/build.xml                            | 27 +++++++++++++++++--
 .../src/org/apache/thrift/TDeserializer.java  |  3 +--
 .../org/apache/thrift/server/THsHaServer.java |  2 +-
 .../thrift/transport/TTransportFactory.java   |  4 +--
 5 files changed, 31 insertions(+), 8 deletions(-)

diff --git a/lib/java/Makefile.am b/lib/java/Makefile.am
index b31b0cd4..9b1e84da 100644
--- 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 7567be4c..af4af07d 100644
--- 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 266906ba..bbfdf21c 100644
--- 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 cdca9236..35f6d3cd 100644
--- 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 63af5da2..c9047fc9 100644
--- 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;
-- 
2.17.1