fix javadoc warnings

9 files changed, 68 insertions, 17 deletions

diff --git a/lib/java/src/org/apache/thrift/EncodingUtils.java b/lib/java/src/org/apache/thrift/EncodingUtils.java
index bf14ef57e..d8cb1082b 100644
--- a/lib/java/src/org/apache/thrift/EncodingUtils.java
+++ b/lib/java/src/org/apache/thrift/EncodingUtils.java
@@ -27,7 +27,7 @@ public class EncodingUtils {
   /**
    * Encode <code>integer</code> as a series of 4 bytes into <code>buf</code>
    * starting at position 0 within that buffer.
-   * 
+   *
    * @param integer
    *          The integer to encode.
    * @param buf
@@ -40,7 +40,7 @@ public class EncodingUtils {
   /**
    * Encode <code>integer</code> as a series of 4 bytes into <code>buf</code>
    * starting at position <code>offset</code>.
-   * 
+   *
    * @param integer
    *          The integer to encode.
    * @param buf
@@ -58,7 +58,7 @@ public class EncodingUtils {
   /**
    * Decode a series of 4 bytes from <code>buf</code>, starting at position 0,
    * and interpret them as an integer.
-   * 
+   *
    * @param buf
    *          The buffer to read from.
    * @return An integer, as read from the buffer.
@@ -70,7 +70,7 @@ public class EncodingUtils {
   /**
    * Decode a series of 4 bytes from <code>buf</code>, start at
    * <code>offset</code>, and interpret them as an integer.
-   * 
+   *
    * @param buf
    *          The buffer to read from.
    * @param offset
@@ -85,6 +85,12 @@ public class EncodingUtils {
   /**
    * Bitfield utilities.
    * Returns true if the bit at position is set in v.
+   *
+   * @param v
+   *          the value whose bit is to be checked.
+   * @param position
+   *          the 0 based bit number indicating the bit to check.
+   * @return true if the bit at position is set in v.
    */
   public static final boolean testBit(byte v, int position) {
     return testBit((int)v, position);
@@ -104,6 +110,12 @@ public class EncodingUtils {
 
   /**
    * Returns v, with the bit at position set to zero.
+   *
+   * @param v
+   *          the value whose bit is to be cleared.
+   * @param position
+   *          the 0 based bit number indicating the bit to clear.
+   * @return v, with the bit at position set to zero.
    */
   public static final byte clearBit(byte v, int position) {
     return (byte)clearBit((int)v, position);
@@ -123,6 +135,14 @@ public class EncodingUtils {
 
   /**
    * Returns v, with the bit at position set to 1 or 0 depending on value.
+   *
+   * @param v
+   *          the value whose bit is to be set.
+   * @param position
+   *          the 0 based bit number indicating the bit to set.
+   * @param value
+   *          if true, the given bit is set to 1; otherwise it is set to 0.
+   * @return v, with the bit at position set to 0 (if value is false) or 1 (if value is true).
    */
   public static final byte setBit(byte v, int position, boolean value) {
     return (byte)setBit((int)v, position, value);
diff --git a/lib/java/src/org/apache/thrift/TDeserializer.java b/lib/java/src/org/apache/thrift/TDeserializer.java
index 8a14cc55b..16070bb6e 100644
--- a/lib/java/src/org/apache/thrift/TDeserializer.java
+++ b/lib/java/src/org/apache/thrift/TDeserializer.java
@@ -42,6 +42,8 @@ public class TDeserializer {
 
   /**
    * Create a new TDeserializer that uses the TBinaryProtocol by default.
+   *
+   * @throws TTransportException
    */
   public TDeserializer() throws TTransportException {
     this(new TBinaryProtocol.Factory());
@@ -52,6 +54,7 @@ public class TDeserializer {
    * factory that is passed in.
    *
    * @param protocolFactory Factory to create a protocol
+   * @throws TTransportException
    */
   public TDeserializer(TProtocolFactory protocolFactory) throws TTransportException {
     trans_ = new TMemoryInputTransport(new TConfiguration());
@@ -136,6 +139,7 @@ public class TDeserializer {
    * @param bytes The serialized object to read from
    * @param fieldIdPathFirst First of the FieldId's that define a path to a boolean field
    * @param fieldIdPathRest The rest FieldId's that define a path to a boolean field
+   * @return the deserialized value.
    * @throws TException if an error is encountered during deserialization.
    */
   public Boolean partialDeserializeBool(byte[] bytes, TFieldIdEnum fieldIdPathFirst, TFieldIdEnum ... fieldIdPathRest) throws TException {
@@ -148,6 +152,7 @@ public class TDeserializer {
    * @param bytes The serialized object to read from
    * @param fieldIdPathFirst First of the FieldId's that define a path to a byte field
    * @param fieldIdPathRest The rest FieldId's that define a path to a byte field
+   * @return the deserialized value.
    * @throws TException if an error is encountered during deserialization.
    */
   public Byte partialDeserializeByte(byte[] bytes, TFieldIdEnum fieldIdPathFirst, TFieldIdEnum ... fieldIdPathRest) throws TException {
@@ -160,6 +165,7 @@ public class TDeserializer {
    * @param bytes The serialized object to read from
    * @param fieldIdPathFirst First of the FieldId's that define a path to a double field
    * @param fieldIdPathRest The rest FieldId's that define a path to a double field
+   * @return the deserialized value.
    * @throws TException if an error is encountered during deserialization.
    */
   public Double partialDeserializeDouble(byte[] bytes, TFieldIdEnum fieldIdPathFirst, TFieldIdEnum ... fieldIdPathRest) throws TException {
@@ -172,6 +178,7 @@ public class TDeserializer {
    * @param bytes The serialized object to read from
    * @param fieldIdPathFirst First of the FieldId's that define a path to an i16 field
    * @param fieldIdPathRest The rest FieldId's that define a path to an i16 field
+   * @return the deserialized value.
    * @throws TException if an error is encountered during deserialization.
    */
   public Short partialDeserializeI16(byte[] bytes, TFieldIdEnum fieldIdPathFirst, TFieldIdEnum ... fieldIdPathRest) throws TException {
@@ -184,6 +191,7 @@ public class TDeserializer {
    * @param bytes The serialized object to read from
    * @param fieldIdPathFirst First of the FieldId's that define a path to an i32 field
    * @param fieldIdPathRest The rest FieldId's that define a path to an i32 field
+   * @return the deserialized value.
    * @throws TException if an error is encountered during deserialization.
    */
   public Integer partialDeserializeI32(byte[] bytes, TFieldIdEnum fieldIdPathFirst, TFieldIdEnum ... fieldIdPathRest) throws TException {
@@ -196,6 +204,7 @@ public class TDeserializer {
    * @param bytes The serialized object to read from
    * @param fieldIdPathFirst First of the FieldId's that define a path to an i64 field
    * @param fieldIdPathRest The rest FieldId's that define a path to an i64 field
+   * @return the deserialized value.
    * @throws TException if an error is encountered during deserialization.
    */
   public Long partialDeserializeI64(byte[] bytes, TFieldIdEnum fieldIdPathFirst, TFieldIdEnum ... fieldIdPathRest) throws TException {
@@ -208,6 +217,7 @@ public class TDeserializer {
    * @param bytes The serialized object to read from
    * @param fieldIdPathFirst First of the FieldId's that define a path to a string field
    * @param fieldIdPathRest The rest FieldId's that define a path to a string field
+   * @return the deserialized value.
    * @throws TException if an error is encountered during deserialization.
    */
   public String partialDeserializeString(byte[] bytes, TFieldIdEnum fieldIdPathFirst, TFieldIdEnum ... fieldIdPathRest) throws TException {
@@ -220,6 +230,7 @@ public class TDeserializer {
    * @param bytes The serialized object to read from
    * @param fieldIdPathFirst First of the FieldId's that define a path to a binary field
    * @param fieldIdPathRest The rest FieldId's that define a path to a binary field
+   * @return the deserialized value.
    * @throws TException if an error is encountered during deserialization.
    */
   public ByteBuffer partialDeserializeByteArray(byte[] bytes, TFieldIdEnum fieldIdPathFirst, TFieldIdEnum ... fieldIdPathRest) throws TException {
@@ -233,6 +244,7 @@ public class TDeserializer {
    * @param bytes The serialized object to read from
    * @param fieldIdPathFirst First of the FieldId's that define a path to a TUnion
    * @param fieldIdPathRest The rest FieldId's that define a path to a TUnion
+   * @return the deserialized value.
    * @throws TException if an error is encountered during deserialization.
    */
   public Short partialDeserializeSetFieldIdInUnion(byte[] bytes, TFieldIdEnum fieldIdPathFirst, TFieldIdEnum ... fieldIdPathRest)  throws TException {
diff --git a/lib/java/src/org/apache/thrift/TMultiplexedProcessor.java b/lib/java/src/org/apache/thrift/TMultiplexedProcessor.java
index c49486217..d797a606f 100644
--- a/lib/java/src/org/apache/thrift/TMultiplexedProcessor.java
+++ b/lib/java/src/org/apache/thrift/TMultiplexedProcessor.java
@@ -70,7 +70,7 @@ public class TMultiplexedProcessor implements TProcessor {
 
     /**
      * Register a service to be called to process queries without service name
-     * @param processor
+     * @param processor the service to be called.
      */
     public void registerDefault(TProcessor processor) {
         defaultProcessor = processor;
diff --git a/lib/java/src/org/apache/thrift/TNonblockingMultiFetchClient.java b/lib/java/src/org/apache/thrift/TNonblockingMultiFetchClient.java
index 78f3a571b..13e8031b6 100644
--- a/lib/java/src/org/apache/thrift/TNonblockingMultiFetchClient.java
+++ b/lib/java/src/org/apache/thrift/TNonblockingMultiFetchClient.java
@@ -118,8 +118,9 @@ public class TNonblockingMultiFetchClient {
   }
 
   /**
-   * return a duplication of requestBuf, so that requestBuf will not
-   * be modified by others.
+   * Returns a copy of requestBuf, so that requestBuf will not be modified by others.
+   *
+   * @return a copy of requestBuf.
    */
   public synchronized ByteBuffer getRequestBuf() {
     if (requestBuf == null) {
@@ -144,7 +145,9 @@ public class TNonblockingMultiFetchClient {
   }
 
   /**
-   * main entry function for fetching from servers
+   * Main entry function for fetching from servers.
+   *
+   * @return The fetched data.
    */
   public synchronized ByteBuffer[] fetch() {
     // clear previous results
diff --git a/lib/java/src/org/apache/thrift/TSerializer.java b/lib/java/src/org/apache/thrift/TSerializer.java
index def4fb69f..8f8502270 100644
--- a/lib/java/src/org/apache/thrift/TSerializer.java
+++ b/lib/java/src/org/apache/thrift/TSerializer.java
@@ -51,6 +51,8 @@ public class TSerializer {
 
   /**
    * Create a new TSerializer that uses the TBinaryProtocol by default.
+   *
+   * @throws TTransportException
    */
   public TSerializer() throws TTransportException {
     this(new TBinaryProtocol.Factory());
@@ -61,6 +63,7 @@ public class TSerializer {
    * factory that is passed in.
    *
    * @param protocolFactory Factory to create a protocol
+   * @throws TTransportException
    */
   public TSerializer(TProtocolFactory protocolFactory) throws TTransportException {
     transport_ = new TIOStreamTransport(new TConfiguration(), baos_);
diff --git a/lib/java/src/org/apache/thrift/TServiceClientFactory.java b/lib/java/src/org/apache/thrift/TServiceClientFactory.java
index 988e65591..7f08ba674 100644
--- a/lib/java/src/org/apache/thrift/TServiceClientFactory.java
+++ b/lib/java/src/org/apache/thrift/TServiceClientFactory.java
@@ -24,12 +24,12 @@ import org.apache.thrift.protocol.TProtocol;
 /**
  * A TServiceClientFactory provides a general way to get a TServiceClient
  * connected to a remote TService via a protocol.
- * @param <T>
+ * @param <T> the type of TServiceClient to get.
  */
 public interface TServiceClientFactory<T extends TServiceClient> {
   /**
    * Get a brand-new T using <i>prot</i> as both the input and output protocol.
-   * @param prot
+   * @param prot The protocol to use for getting T.
    * @return A brand-new T using <i>prot</i> as both the input and output protocol.
    */
   public T getClient(TProtocol prot);
@@ -37,8 +37,8 @@ public interface TServiceClientFactory<T extends TServiceClient> {
   /**
    * Get a brand new T using the specified input and output protocols. The
    * input and output protocols may be the same instance.
-   * @param iprot
-   * @param oprot
+   * @param iprot The input protocol to use for getting T.
+   * @param oprot The output protocol to use for getting T.
    * @return a brand new T using the specified input and output protocols
    */
   public T getClient(TProtocol iprot, TProtocol oprot);
diff --git a/lib/java/src/org/apache/thrift/TUnion.java b/lib/java/src/org/apache/thrift/TUnion.java
index 388aef743..cf22749c5 100644
--- a/lib/java/src/org/apache/thrift/TUnion.java
+++ b/lib/java/src/org/apache/thrift/TUnion.java
@@ -168,6 +168,7 @@ public abstract class TUnion<T extends TUnion<T,F>, F extends TFieldIdEnum> impl
    * @param iprot input protocol from which to read a value.
    * @param field the field whose value is to be read from iprot.
    * @return read Object based on the field header, as specified by the argument.
+   * @throws TException
    */
   protected abstract Object standardSchemeReadValue(TProtocol iprot, TField field) throws TException;
   protected abstract void standardSchemeWriteValue(TProtocol oprot) throws TException;
diff --git a/lib/java/src/org/apache/thrift/async/TAsyncClient.java b/lib/java/src/org/apache/thrift/async/TAsyncClient.java
index 005018a83..8ba135642 100644
--- a/lib/java/src/org/apache/thrift/async/TAsyncClient.java
+++ b/lib/java/src/org/apache/thrift/async/TAsyncClient.java
@@ -92,7 +92,9 @@ public abstract class TAsyncClient {
   }
 
   /**
-   * Called by delegate method on error
+   * Called by delegate method on error.
+   *
+   * @param exception the exception indicating the current error condition.
    */
   protected void onError(Exception exception) {
     ___transport.close();
diff --git a/lib/java/src/org/apache/thrift/transport/TByteBuffer.java b/lib/java/src/org/apache/thrift/transport/TByteBuffer.java
index c792f3b1c..72d10c53d 100644
--- a/lib/java/src/org/apache/thrift/transport/TByteBuffer.java
+++ b/lib/java/src/org/apache/thrift/transport/TByteBuffer.java
@@ -14,6 +14,9 @@ public final class TByteBuffer extends TEndpointTransport {
 
   /**
    * Creates a new TByteBuffer wrapping a given NIO ByteBuffer.
+   *
+   * @param byteBuffer the NIO ByteBuffer to wrap.
+   * @throws TTransportException on error.
    */
   public TByteBuffer(ByteBuffer byteBuffer) throws TTransportException {
     super(new TConfiguration());
@@ -60,7 +63,9 @@ public final class TByteBuffer extends TEndpointTransport {
   }
 
   /**
-   * Get the underlying NIO ByteBuffer.
+   * Gets the underlying NIO ByteBuffer.
+   *
+   * @return the underlying NIO ByteBuffer.
    */
   public ByteBuffer getByteBuffer() {
     return byteBuffer;
@@ -68,6 +73,8 @@ public final class TByteBuffer extends TEndpointTransport {
 
   /**
    * Convenience method to call clear() on the underlying NIO ByteBuffer.
+   *
+   * @return this instance.
    */
   public TByteBuffer clear() {
     byteBuffer.clear();
@@ -76,15 +83,18 @@ public final class TByteBuffer extends TEndpointTransport {
 
   /**
    * Convenience method to call flip() on the underlying NIO ByteBuffer.
-     */
+   *
+   * @return this instance.
+   */
   public TByteBuffer flip() {
     byteBuffer.flip();
     return this;
   }
 
   /**
-   * Convenience method to convert the underlying NIO ByteBuffer to a
-   * plain old byte array.
+   * Convenience method to convert the underlying NIO ByteBuffer to a plain old byte array.
+   *
+   * @return the byte array backing the underlying NIO ByteBuffer.
    */
   public byte[] toByteArray() {
     final byte[] data = new byte[byteBuffer.remaining()];