Add missing javadoc

10 files changed, 64 insertions, 34 deletions

diff --git a/lib/java/src/org/apache/thrift/Option.java b/lib/java/src/org/apache/thrift/Option.java
index d5cd309e8..f02eae046 100644
--- a/lib/java/src/org/apache/thrift/Option.java
+++ b/lib/java/src/org/apache/thrift/Option.java
@@ -96,8 +96,8 @@ public abstract class Option<T> {
 
     /**
      * Wraps value in an Option type, depending on whether or not value is null
-     * @param value
-     * @param <T> type of value
+     * @param value the value to wrap in Option
+     * @param <T> the type of value
      * @return Some(value) if value is not null, None if value is null
      */
     public static <T> Option<T> fromNullable(T value) {
@@ -110,8 +110,8 @@ public abstract class Option<T> {
 
     /**
      * Wrap value in a Some type (NB! value must not be null!)
-     * @param value
-     * @param <T> type of value
+     * @param value the value to wrap.
+     * @param <T> the type of value
      * @return a new Some(value)
      */
     public static <T> Some<T> some(T value) {
@@ -122,4 +122,4 @@ public abstract class Option<T> {
     public static <T> None<T> none() {
         return (None<T>) NONE;
     }
-}
\ No newline at end of file
+}
diff --git a/lib/java/src/org/apache/thrift/TApplicationException.java b/lib/java/src/org/apache/thrift/TApplicationException.java
index 4d693d9ce..59cff6930 100644
--- a/lib/java/src/org/apache/thrift/TApplicationException.java
+++ b/lib/java/src/org/apache/thrift/TApplicationException.java
@@ -125,6 +125,10 @@ public class TApplicationException extends TException implements TSerializable {
 
   /**
    * Convenience factory method for constructing a TApplicationException given a TProtocol input
+   *
+   * @param iprot protocol from which an instance of TApplicationException is read.
+   * @return an instance of TApplicationException read from iprot.
+   * @throws TException if there is an error reading from iprot.
    */
   public static TApplicationException readFrom(TProtocol iprot) throws TException
   {
diff --git a/lib/java/src/org/apache/thrift/TAsyncProcessor.java b/lib/java/src/org/apache/thrift/TAsyncProcessor.java
index 5e287d5c9..d435b08c5 100644
--- a/lib/java/src/org/apache/thrift/TAsyncProcessor.java
+++ b/lib/java/src/org/apache/thrift/TAsyncProcessor.java
@@ -27,6 +27,7 @@ public interface TAsyncProcessor {
    * <b>Note:</b> Implementations must call fb.responseReady() once processing
    * is complete
    *
+   * @param fb the frame buffer to process.
    * @throws TException if the frame cannot be processed
    */
   public void process(final AsyncFrameBuffer fb) throws TException;
diff --git a/lib/java/src/org/apache/thrift/TBase.java b/lib/java/src/org/apache/thrift/TBase.java
index e1489d530..be8ef9ba9 100644
--- a/lib/java/src/org/apache/thrift/TBase.java
+++ b/lib/java/src/org/apache/thrift/TBase.java
@@ -31,13 +31,17 @@ public interface TBase<T extends TBase<T,F>, F extends TFieldIdEnum> extends Com
 
   /**
    * Get the F instance that corresponds to fieldId.
+   *
+   * @param fieldId the ID of the requested field.
+   * @return F instance that corresponds to fieldId.
    */
   public F fieldForId(int fieldId);
 
   /**
    * Check if a field is currently set or unset.
    *
-   * @param field
+   * @param field the field to check.
+   * @return true if the field is set, false otherwise.
    */
   public boolean isSet(F field);
 
@@ -45,7 +49,8 @@ public interface TBase<T extends TBase<T,F>, F extends TFieldIdEnum> extends Com
    * Get a field's value by field variable. Primitive types will be wrapped in
    * the appropriate "boxed" types.
    *
-   * @param field
+   * @param field the field whose value is requested.
+   * @return the value of the requested field.
    */
   public Object getFieldValue(F field);
 
@@ -53,10 +58,16 @@ public interface TBase<T extends TBase<T,F>, F extends TFieldIdEnum> extends Com
    * Set a field's value by field variable. Primitive types must be "boxed" in
    * the appropriate object wrapper type.
    *
-   * @param field
+   * @param field the field whose value is to be set.
+   * @param value the value to be assigned to field.
    */
   public void setFieldValue(F field, Object value);
 
+  /**
+   * Performs a deep copy of this instance and returns the copy.
+   *
+   * @return a deep copy of this instance.
+   */
   public T deepCopy();
 
   /**
diff --git a/lib/java/src/org/apache/thrift/TDeserializer.java b/lib/java/src/org/apache/thrift/TDeserializer.java
index 29be5578f..8a14cc55b 100644
--- a/lib/java/src/org/apache/thrift/TDeserializer.java
+++ b/lib/java/src/org/apache/thrift/TDeserializer.java
@@ -63,6 +63,7 @@ public class TDeserializer {
    *
    * @param base The object to read into
    * @param bytes The array to read from
+   * @throws TException if an error is encountered during deserialization.
    */
   public void deserialize(TBase base, byte[] bytes) throws TException {
       deserialize(base, bytes, 0, bytes.length);
@@ -75,6 +76,7 @@ public class TDeserializer {
    * @param bytes The array to read from
    * @param offset The offset into {@code bytes}
    * @param length The length to read from {@code bytes}
+   * @throws TException if an error is encountered during deserialization.
    */
   public void deserialize(TBase base, byte[] bytes, int offset, int length) throws TException {
     try {
@@ -93,6 +95,7 @@ public class TDeserializer {
    * @param base The object to read into
    * @param data The string to read from
    * @param charset Valid JVM charset
+   * @throws TException if an error is encountered during deserialization.
    */
   public void deserialize(TBase base, String data, String charset) throws TException {
     try {
@@ -111,7 +114,7 @@ public class TDeserializer {
    * @param bytes The serialized object to read from
    * @param fieldIdPathFirst First of the FieldId's that define a path tb
    * @param fieldIdPathRest The rest FieldId's that define a path tb
-   * @throws TException
+   * @throws TException if an error is encountered during deserialization.
    */
   public void partialDeserialize(TBase tb, byte[] bytes, TFieldIdEnum fieldIdPathFirst, TFieldIdEnum ... fieldIdPathRest) throws TException {
     try {
@@ -133,7 +136,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
-   * @throws TException
+   * @throws TException if an error is encountered during deserialization.
    */
   public Boolean partialDeserializeBool(byte[] bytes, TFieldIdEnum fieldIdPathFirst, TFieldIdEnum ... fieldIdPathRest) throws TException {
     return (Boolean) partialDeserializeField(TType.BOOL, bytes, fieldIdPathFirst, fieldIdPathRest);
@@ -145,7 +148,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
-   * @throws TException
+   * @throws TException if an error is encountered during deserialization.
    */
   public Byte partialDeserializeByte(byte[] bytes, TFieldIdEnum fieldIdPathFirst, TFieldIdEnum ... fieldIdPathRest) throws TException {
     return (Byte) partialDeserializeField(TType.BYTE, bytes, fieldIdPathFirst, fieldIdPathRest);
@@ -157,7 +160,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
-   * @throws TException
+   * @throws TException if an error is encountered during deserialization.
    */
   public Double partialDeserializeDouble(byte[] bytes, TFieldIdEnum fieldIdPathFirst, TFieldIdEnum ... fieldIdPathRest) throws TException {
     return (Double) partialDeserializeField(TType.DOUBLE, bytes, fieldIdPathFirst, fieldIdPathRest);
@@ -169,7 +172,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
-   * @throws TException
+   * @throws TException if an error is encountered during deserialization.
    */
   public Short partialDeserializeI16(byte[] bytes, TFieldIdEnum fieldIdPathFirst, TFieldIdEnum ... fieldIdPathRest) throws TException {
     return (Short) partialDeserializeField(TType.I16, bytes, fieldIdPathFirst, fieldIdPathRest);
@@ -181,7 +184,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
-   * @throws TException
+   * @throws TException if an error is encountered during deserialization.
    */
   public Integer partialDeserializeI32(byte[] bytes, TFieldIdEnum fieldIdPathFirst, TFieldIdEnum ... fieldIdPathRest) throws TException {
     return (Integer) partialDeserializeField(TType.I32, bytes, fieldIdPathFirst, fieldIdPathRest);
@@ -193,7 +196,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
-   * @throws TException
+   * @throws TException if an error is encountered during deserialization.
    */
   public Long partialDeserializeI64(byte[] bytes, TFieldIdEnum fieldIdPathFirst, TFieldIdEnum ... fieldIdPathRest) throws TException {
     return (Long) partialDeserializeField(TType.I64, bytes, fieldIdPathFirst, fieldIdPathRest);
@@ -205,7 +208,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
-   * @throws TException
+   * @throws TException if an error is encountered during deserialization.
    */
   public String partialDeserializeString(byte[] bytes, TFieldIdEnum fieldIdPathFirst, TFieldIdEnum ... fieldIdPathRest) throws TException {
     return (String) partialDeserializeField(TType.STRING, bytes, fieldIdPathFirst, fieldIdPathRest);
@@ -217,7 +220,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
-   * @throws TException
+   * @throws TException if an error is encountered during deserialization.
    */
   public ByteBuffer partialDeserializeByteArray(byte[] bytes, TFieldIdEnum fieldIdPathFirst, TFieldIdEnum ... fieldIdPathRest) throws TException {
     // TType does not have binary, so we use the arbitrary num 100
@@ -230,7 +233,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
-   * @throws TException
+   * @throws TException if an error is encountered during deserialization.
    */
   public Short partialDeserializeSetFieldIdInUnion(byte[] bytes, TFieldIdEnum fieldIdPathFirst, TFieldIdEnum ... fieldIdPathRest)  throws TException {
     try {
@@ -333,6 +336,7 @@ public class TDeserializer {
    *
    * @param base The object to read into
    * @param data The string to read from
+   * @throws TException if an error is encountered during deserialization.
    */
   public void fromString(TBase base, String data) throws TException {
     deserialize(base, data.getBytes());
diff --git a/lib/java/src/org/apache/thrift/TFieldIdEnum.java b/lib/java/src/org/apache/thrift/TFieldIdEnum.java
index 2956fba0b..20b845e61 100644
--- a/lib/java/src/org/apache/thrift/TFieldIdEnum.java
+++ b/lib/java/src/org/apache/thrift/TFieldIdEnum.java
@@ -23,12 +23,16 @@ package org.apache.thrift;
  */
 public interface TFieldIdEnum {
   /**
-   * Get the Thrift field id for the named field.
+   * Gets the Thrift field id for the named field.
+   *
+   * @return the Thrift field id for the named field.
    */
   public short getThriftFieldId();
 
   /**
-   * Get the field's name, exactly as in the IDL.
+   * Gets the field's name, exactly as in the IDL.
+   *
+   * @return the field's name, exactly as in the IDL.
    */
   public String getFieldName();
 }
diff --git a/lib/java/src/org/apache/thrift/TSerializable.java b/lib/java/src/org/apache/thrift/TSerializable.java
index 80002c761..317814b45 100644
--- a/lib/java/src/org/apache/thrift/TSerializable.java
+++ b/lib/java/src/org/apache/thrift/TSerializable.java
@@ -31,6 +31,7 @@ public interface TSerializable {
    * Reads the TObject from the given input protocol.
    *
    * @param iprot Input protocol
+   * @throws TException if there is an error reading from iprot
    */
   public void read(TProtocol iprot) throws TException;
 
@@ -38,6 +39,7 @@ public interface TSerializable {
    * Writes the objects out to the protocol
    *
    * @param oprot Output protocol
+   * @throws TException if there is an error writing to oprot
    */
   public void write(TProtocol oprot) throws TException;
 
diff --git a/lib/java/src/org/apache/thrift/TSerializer.java b/lib/java/src/org/apache/thrift/TSerializer.java
index 90cc0398f..def4fb69f 100644
--- a/lib/java/src/org/apache/thrift/TSerializer.java
+++ b/lib/java/src/org/apache/thrift/TSerializer.java
@@ -74,6 +74,7 @@ public class TSerializer {
    *
    * @param base The object to serialize
    * @return Serialized object in byte[] format
+   * @throws TException if an error is encountered during serialization.
    */
   public byte[] serialize(TBase base) throws TException {
     baos_.reset();
@@ -87,9 +88,9 @@ public class TSerializer {
    *
    * @param base The object to serialize
    * @return Serialized object as a String
+   * @throws TException if an error is encountered during serialization.
    */
   public String toString(TBase base) throws TException {
     return new String(serialize(base));
   }
 }
-
diff --git a/lib/java/src/org/apache/thrift/TUnion.java b/lib/java/src/org/apache/thrift/TUnion.java
index 1ef11df49..388aef743 100644
--- a/lib/java/src/org/apache/thrift/TUnion.java
+++ b/lib/java/src/org/apache/thrift/TUnion.java
@@ -43,7 +43,7 @@ public abstract class TUnion<T extends TUnion<T,F>, F extends TFieldIdEnum> impl
     setField_ = null;
     value_ = null;
   }
-  
+
   private static final Map<Class<? extends IScheme>, SchemeFactory> schemes = new HashMap<Class<? extends IScheme>, SchemeFactory>();
   static {
     schemes.put(StandardScheme.class, new TUnionStandardSchemeFactory());
@@ -153,22 +153,25 @@ public abstract class TUnion<T extends TUnion<T,F>, F extends TFieldIdEnum> impl
   }
 
   /**
-   * Implementation should be generated so that we can efficiently type check 
+   * Implementation should be generated so that we can efficiently type check
    * various values.
-   * @param setField
-   * @param value
+   * @param setField the field to assign value to.
+   * @param value the value to be assigned to setField.
+   * @throws ClassCastException if the type of value is incompatible with the type of setField.
    */
   protected abstract void checkType(F setField, Object value) throws ClassCastException;
 
   /**
-   * Implementation should be generated to read the right stuff from the wire 
-   * based on the field header. 
-   * @param field
+   * Implementation should be generated to read the right stuff from the wire
+   * based on the field header.
+   *
+   * @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.
    */
   protected abstract Object standardSchemeReadValue(TProtocol iprot, TField field) throws TException;
   protected abstract void standardSchemeWriteValue(TProtocol oprot) throws TException;
-  
+
   protected abstract Object tupleSchemeReadValue(TProtocol iprot, short fieldID) throws TException;
   protected abstract void tupleSchemeWriteValue(TProtocol oprot) throws TException;
 
@@ -203,13 +206,13 @@ public abstract class TUnion<T extends TUnion<T,F>, F extends TFieldIdEnum> impl
     this.setField_ = null;
     this.value_ = null;
   }
-  
+
   private static class TUnionStandardSchemeFactory implements SchemeFactory {
     public TUnionStandardScheme getScheme() {
       return new TUnionStandardScheme();
     }
   }
-  
+
   private static class TUnionStandardScheme extends StandardScheme<TUnion> {
 
     @Override
@@ -247,13 +250,13 @@ public abstract class TUnion<T extends TUnion<T,F>, F extends TFieldIdEnum> impl
       oprot.writeStructEnd();
     }
   }
-  
+
   private static class TUnionTupleSchemeFactory implements SchemeFactory {
     public TUnionTupleScheme getScheme() {
       return new TUnionTupleScheme();
     }
   }
-  
+
   private static class TUnionTupleScheme extends TupleScheme<TUnion> {
 
     @Override
diff --git a/lib/java/src/org/apache/thrift/utils/StringUtils.java b/lib/java/src/org/apache/thrift/utils/StringUtils.java
index 9b9671b69..b54388a5b 100644
--- a/lib/java/src/org/apache/thrift/utils/StringUtils.java
+++ b/lib/java/src/org/apache/thrift/utils/StringUtils.java
@@ -30,7 +30,7 @@ public final class StringUtils {
   /**
    * Stringify a byte array to the hex representation for each byte.
    *
-   * @param bytes
+   * @param bytes the byte array to convert to hex string.
    * @return hex string.
    */
   public static String bytesToHexString(byte[] bytes) {