JavaDoc updates.

16 files changed, 92 insertions, 10 deletions

diff --git a/core/src/main/java/org/bouncycastle/asn1/ASN1Boolean.java b/core/src/main/java/org/bouncycastle/asn1/ASN1Boolean.java
index 1d4f5af0..e817c187 100644
--- a/core/src/main/java/org/bouncycastle/asn1/ASN1Boolean.java
+++ b/core/src/main/java/org/bouncycastle/asn1/ASN1Boolean.java
@@ -19,7 +19,9 @@ public class ASN1Boolean
     /**
      * return a boolean from the passed in object.
      *
+     * @param obj an ASN1Boolean or an object that can be converted into one.
      * @exception IllegalArgumentException if the object cannot be converted.
+     * @return an ASN1Boolean instance.
      */
     public static ASN1Boolean getInstance(
         Object  obj)
@@ -47,6 +49,7 @@ public class ASN1Boolean
 
     /**
      * return an ASN1Boolean from the passed in boolean.
+     * @return an ASN1Boolean instance.
      */
     public static ASN1Boolean getInstance(
         boolean  value)
@@ -56,6 +59,7 @@ public class ASN1Boolean
 
     /**
      * return an ASN1Boolean from the passed in value.
+     * @return an ASN1Boolean instance.
      */
     public static ASN1Boolean getInstance(
         int value)
@@ -71,6 +75,7 @@ public class ASN1Boolean
      *              tagged false otherwise.
      * @exception IllegalArgumentException if the tagged object cannot
      *               be converted.
+     * @return an ASN1Boolean instance.
      */
     public static ASN1Boolean getInstance(
         ASN1TaggedObject obj,
diff --git a/core/src/main/java/org/bouncycastle/asn1/ASN1Enumerated.java b/core/src/main/java/org/bouncycastle/asn1/ASN1Enumerated.java
index 09a518f6..7b4e7981 100644
--- a/core/src/main/java/org/bouncycastle/asn1/ASN1Enumerated.java
+++ b/core/src/main/java/org/bouncycastle/asn1/ASN1Enumerated.java
@@ -11,9 +11,11 @@ public class ASN1Enumerated
     byte[]      bytes;
 
     /**
-     * return an integer from the passed in object
+     * return an enumerated from the passed in object
      *
+     * @param obj an ASN1Enumerated or an object that can be converted into one.
      * @exception IllegalArgumentException if the object cannot be converted.
+     * @return an ASN1Enumerated instance.
      */
     public static ASN1Enumerated getInstance(
         Object  obj)
@@ -46,6 +48,7 @@ public class ASN1Enumerated
      *              tagged false otherwise.
      * @exception IllegalArgumentException if the tagged object cannot
      *               be converted.
+     * @return an ASN1Enumerated instance.
      */
     public static ASN1Enumerated getInstance(
         ASN1TaggedObject obj,
@@ -64,7 +67,9 @@ public class ASN1Enumerated
     }
 
     /**
-     * @deprecated use ASN1Enumerated
+     * Constructor from int.
+     *
+     * @param value the value of this enumerated.
      */
     public ASN1Enumerated(
         int         value)
@@ -73,7 +78,9 @@ public class ASN1Enumerated
     }
 
     /**
-     * @deprecated use ASN1Enumerated
+     * Constructor from BigInteger
+     *
+     * @param value the value of this enumerated.
      */
     public ASN1Enumerated(
         BigInteger   value)
@@ -82,7 +89,9 @@ public class ASN1Enumerated
     }
 
     /**
-     * @deprecated use ASN1Enumerated
+     * Constructor from encoded BigInteger.
+     *
+     * @param bytes the value of this enumerated as an encoded BigInteger (signed).
      */
     public ASN1Enumerated(
         byte[]   bytes)
diff --git a/core/src/main/java/org/bouncycastle/asn1/ASN1GeneralizedTime.java b/core/src/main/java/org/bouncycastle/asn1/ASN1GeneralizedTime.java
index d38aa1c0..e096cfee 100644
--- a/core/src/main/java/org/bouncycastle/asn1/ASN1GeneralizedTime.java
+++ b/core/src/main/java/org/bouncycastle/asn1/ASN1GeneralizedTime.java
@@ -18,7 +18,9 @@ public class ASN1GeneralizedTime
        /**
         * return a generalized time from the passed in object
         *
+        * @param obj an ASN1GeneralizedTime or an object that can be converted into one.
         * @exception IllegalArgumentException if the object cannot be converted.
+        * @return an ASN1GeneralizedTime instance, or null.
         */
        public static ASN1GeneralizedTime getInstance(
            Object  obj)
@@ -51,6 +53,7 @@ public class ASN1GeneralizedTime
         *              tagged false otherwise.
         * @exception IllegalArgumentException if the tagged object cannot
         *               be converted.
+        * @return an ASN1GeneralizedTime instance.
         */
        public static ASN1GeneralizedTime getInstance(
            ASN1TaggedObject obj,
diff --git a/core/src/main/java/org/bouncycastle/asn1/ASN1InputStream.java b/core/src/main/java/org/bouncycastle/asn1/ASN1InputStream.java
index 59392713..1971af92 100644
--- a/core/src/main/java/org/bouncycastle/asn1/ASN1InputStream.java
+++ b/core/src/main/java/org/bouncycastle/asn1/ASN1InputStream.java
@@ -124,6 +124,12 @@ public class ASN1InputStream
 
     /**
      * build an object given its tag and the number of bytes to construct it from.
+     *
+     * @param tag the full tag details.
+     * @param tagNo the tagNo defined.
+     * @param length the length of the object.
+     * @return the resulting primitive.
+     * @throws java.io.IOException on processing exception.
      */
     protected ASN1Primitive buildObject(
         int       tag,
diff --git a/core/src/main/java/org/bouncycastle/asn1/ASN1Integer.java b/core/src/main/java/org/bouncycastle/asn1/ASN1Integer.java
index b951e745..572e412a 100644
--- a/core/src/main/java/org/bouncycastle/asn1/ASN1Integer.java
+++ b/core/src/main/java/org/bouncycastle/asn1/ASN1Integer.java
@@ -13,7 +13,9 @@ public class ASN1Integer
     /**
      * return an integer from the passed in object
      *
+     * @param obj an ASN1Integer or an object that can be converted into one.
      * @throws IllegalArgumentException if the object cannot be converted.
+     * @return an ASN1Integer instance.
      */
     public static ASN1Integer getInstance(
         Object obj)
@@ -46,6 +48,7 @@ public class ASN1Integer
      *                 tagged false otherwise.
      * @throws IllegalArgumentException if the tagged object cannot
      * be converted.
+     * @return an ASN1Integer instance.
      */
     public static ASN1Integer getInstance(
         ASN1TaggedObject obj,
@@ -94,6 +97,7 @@ public class ASN1Integer
     /**
      * in some cases positive values get crammed into a space,
      * that's not quite big enough...
+     * @return the BigInteger that results from treating this ASN.1 INTEGER as unsigned.
      */
     public BigInteger getPositiveValue()
     {
diff --git a/core/src/main/java/org/bouncycastle/asn1/ASN1ObjectIdentifier.java b/core/src/main/java/org/bouncycastle/asn1/ASN1ObjectIdentifier.java
index 6bd335bc..e4e92f25 100644
--- a/core/src/main/java/org/bouncycastle/asn1/ASN1ObjectIdentifier.java
+++ b/core/src/main/java/org/bouncycastle/asn1/ASN1ObjectIdentifier.java
@@ -15,8 +15,9 @@ public class ASN1ObjectIdentifier
 
     /**
      * return an OID from the passed in object
-     *
+     * @param obj an ASN1ObjectIdentifier or an object that can be converted into one.
      * @throws IllegalArgumentException if the object cannot be converted.
+     * @return an ASN1ObjectIdentifier instance, or null.
      */
     public static ASN1ObjectIdentifier getInstance(
         Object obj)
@@ -55,6 +56,7 @@ public class ASN1ObjectIdentifier
      *                 tagged false otherwise.
      * @throws IllegalArgumentException if the tagged object cannot
      * be converted.
+     * @return an ASN1ObjectIdentifier instance, or null.
      */
     public static ASN1ObjectIdentifier getInstance(
         ASN1TaggedObject obj,
diff --git a/core/src/main/java/org/bouncycastle/asn1/ASN1Sequence.java b/core/src/main/java/org/bouncycastle/asn1/ASN1Sequence.java
index 0507a2bd..ff3876ca 100644
--- a/core/src/main/java/org/bouncycastle/asn1/ASN1Sequence.java
+++ b/core/src/main/java/org/bouncycastle/asn1/ASN1Sequence.java
@@ -14,6 +14,7 @@ public abstract class ASN1Sequence
      *
      * @param obj the object we want converted.
      * @exception IllegalArgumentException if the object cannot be converted.
+     * @return an ASN1Sequence instance, or null.
      */
     public static ASN1Sequence getInstance(
         Object  obj)
@@ -65,6 +66,7 @@ public abstract class ASN1Sequence
      *          false otherwise.
      * @exception IllegalArgumentException if the tagged object cannot
      *          be converted.
+     * @return an ASN1Sequence instance.
      */
     public static ASN1Sequence getInstance(
         ASN1TaggedObject    obj,
@@ -118,6 +120,7 @@ public abstract class ASN1Sequence
 
     /**
      * create a sequence containing one object
+     * @param obj the object to be put in the SEQUENCE.
      */
     protected ASN1Sequence(
         ASN1Encodable obj)
@@ -127,6 +130,7 @@ public abstract class ASN1Sequence
 
     /**
      * create a sequence containing a vector of objects.
+     * @param v the vector of objects to be put in the SEQUENCE
      */
     protected ASN1Sequence(
         ASN1EncodableVector v)
diff --git a/core/src/main/java/org/bouncycastle/asn1/ASN1Set.java b/core/src/main/java/org/bouncycastle/asn1/ASN1Set.java
index f1ac6c7d..3e1662b6 100644
--- a/core/src/main/java/org/bouncycastle/asn1/ASN1Set.java
+++ b/core/src/main/java/org/bouncycastle/asn1/ASN1Set.java
@@ -16,6 +16,7 @@ abstract public class ASN1Set
      *
      * @param obj the object we want converted.
      * @exception IllegalArgumentException if the object cannot be converted.
+     * @return an ASN1Set instance, or null.
      */
     public static ASN1Set getInstance(
         Object  obj)
@@ -67,6 +68,7 @@ abstract public class ASN1Set
      *          false otherwise.
      * @exception IllegalArgumentException if the tagged object cannot
      *          be converted.
+     * @return an ASN1Set instance.
      */
     public static ASN1Set getInstance(
         ASN1TaggedObject    obj,
@@ -135,6 +137,7 @@ abstract public class ASN1Set
 
     /**
      * create a sequence containing one object
+     * @param obj object to be added to the SET.
      */
     protected ASN1Set(
         ASN1Encodable obj)
@@ -144,6 +147,8 @@ abstract public class ASN1Set
 
     /**
      * create a sequence containing a vector of objects.
+     * @param v a vector of objects to make up the SET.
+     * @param doSort true if should be sorted DER style, false otherwise.
      */
     protected ASN1Set(
         ASN1EncodableVector v,
diff --git a/core/src/main/java/org/bouncycastle/asn1/ASN1UTCTime.java b/core/src/main/java/org/bouncycastle/asn1/ASN1UTCTime.java
index fc7ff636..23a9e6c4 100644
--- a/core/src/main/java/org/bouncycastle/asn1/ASN1UTCTime.java
+++ b/core/src/main/java/org/bouncycastle/asn1/ASN1UTCTime.java
@@ -17,7 +17,9 @@ public class ASN1UTCTime
     /**
      * return an UTC Time from the passed in object.
      *
+     * @param obj an ASN1UTCTime or an object that can be converted into one.
      * @exception IllegalArgumentException if the object cannot be converted.
+     * @return an ASN1UTCTime instance, or null.
      */
     public static ASN1UTCTime getInstance(
         Object  obj)
@@ -50,6 +52,7 @@ public class ASN1UTCTime
      *              tagged false otherwise.
      * @exception IllegalArgumentException if the tagged object cannot
      *               be converted.
+     * @return an ASN1UTCTime instance, or null.
      */
     public static ASN1UTCTime getInstance(
         ASN1TaggedObject obj,
@@ -92,7 +95,8 @@ public class ASN1UTCTime
     }
 
     /**
-     * base constructer from a java.util.date object
+     * base constructor from a java.util.date object
+     * @param time the Date to build the time from.
      */
     public ASN1UTCTime(
         Date time)
diff --git a/core/src/main/java/org/bouncycastle/asn1/DERBMPString.java b/core/src/main/java/org/bouncycastle/asn1/DERBMPString.java
index 341e46a6..635300b4 100644
--- a/core/src/main/java/org/bouncycastle/asn1/DERBMPString.java
+++ b/core/src/main/java/org/bouncycastle/asn1/DERBMPString.java
@@ -18,6 +18,7 @@ public class DERBMPString
      *
      * @param obj the object we want converted.
      * @exception IllegalArgumentException if the object cannot be converted.
+     * @return a DERBMPString instance, or null.
      */
     public static DERBMPString getInstance(
         Object  obj)
@@ -50,6 +51,7 @@ public class DERBMPString
      *              tagged false otherwise.
      * @exception IllegalArgumentException if the tagged object cannot
      *              be converted.
+     * @return a DERBMPString instance.
      */
     public static DERBMPString getInstance(
         ASN1TaggedObject obj,
@@ -69,6 +71,7 @@ public class DERBMPString
 
     /**
      * basic constructor - byte encoded string.
+     * @param string the encoded BMP STRING to wrap.
      */
     DERBMPString(
         byte[]   string)
@@ -90,6 +93,7 @@ public class DERBMPString
 
     /**
      * basic constructor
+     * @param string a String to wrap as a BMP STRING.
      */
     public DERBMPString(
         String   string)
diff --git a/core/src/main/java/org/bouncycastle/asn1/DERBitString.java b/core/src/main/java/org/bouncycastle/asn1/DERBitString.java
index a7b02ec6..4852a796 100644
--- a/core/src/main/java/org/bouncycastle/asn1/DERBitString.java
+++ b/core/src/main/java/org/bouncycastle/asn1/DERBitString.java
@@ -18,7 +18,8 @@ public class DERBitString
     protected int         padBits;
 
     /**
-     * return the correct number of pad bits for a bit string defined in
+     * @param bitString an int containing the BIT STRING
+     * @return the correct number of pad bits for a bit string defined in
      * a 32 bit constant
      */
     static protected int getPadBits(
@@ -66,7 +67,8 @@ public class DERBitString
     }
 
     /**
-     * return the correct number of bytes for a bit string defined in
+     * @param bitString an int containing the BIT STRING
+     * @return the correct number of bytes for a bit string defined in
      * a 32 bit constant
      */
     static protected byte[] getBytes(int bitString)
@@ -93,7 +95,9 @@ public class DERBitString
     /**
      * return a Bit String from the passed in object
      *
+     * @param obj a DERBitString or an object that can be converted into one.
      * @exception IllegalArgumentException if the object cannot be converted.
+     * @return a DERBitString instance, or null.
      */
     public static DERBitString getInstance(
         Object  obj)
@@ -114,6 +118,7 @@ public class DERBitString
      *              tagged false otherwise.
      * @exception IllegalArgumentException if the tagged object cannot
      *               be converted.
+     * @return a DERBitString instance, or null.
      */
     public static DERBitString getInstance(
         ASN1TaggedObject obj,
diff --git a/core/src/main/java/org/bouncycastle/asn1/DEREnumerated.java b/core/src/main/java/org/bouncycastle/asn1/DEREnumerated.java
index 879a01ca..daa8777e 100644
--- a/core/src/main/java/org/bouncycastle/asn1/DEREnumerated.java
+++ b/core/src/main/java/org/bouncycastle/asn1/DEREnumerated.java
@@ -8,16 +8,28 @@ import java.math.BigInteger;
 public class DEREnumerated
     extends ASN1Enumerated
 {
+    /**
+     * @param bytes the value of this enumerated as an encoded BigInteger (signed).
+     * @deprecated use ASN1Enumerated
+     */
     DEREnumerated(byte[] bytes)
     {
         super(bytes);
     }
 
+    /**
+     * @param value the value of this enumerated.
+     * @deprecated use ASN1Enumerated
+     */
     public DEREnumerated(BigInteger value)
     {
         super(value);
     }
 
+    /**
+     * @param value the value of this enumerated.
+     * @deprecated use ASN1Enumerated
+     */
     public DEREnumerated(int value)
     {
         super(value);
diff --git a/core/src/main/java/org/bouncycastle/asn1/DERIA5String.java b/core/src/main/java/org/bouncycastle/asn1/DERIA5String.java
index 631672ef..1c533b10 100644
--- a/core/src/main/java/org/bouncycastle/asn1/DERIA5String.java
+++ b/core/src/main/java/org/bouncycastle/asn1/DERIA5String.java
@@ -17,7 +17,9 @@ public class DERIA5String
     /**
      * return a IA5 string from the passed in object
      *
+     * @param obj a DERIA5String or an object that can be converted into one.
      * @exception IllegalArgumentException if the object cannot be converted.
+     * @return a DERIA5String instance, or null.
      */
     public static DERIA5String getInstance(
         Object  obj)
@@ -50,6 +52,7 @@ public class DERIA5String
      *              tagged false otherwise.
      * @exception IllegalArgumentException if the tagged object cannot
      *               be converted.
+     * @return a DERIA5String instance, or null.
      */
     public static DERIA5String getInstance(
         ASN1TaggedObject obj,
@@ -69,6 +72,7 @@ public class DERIA5String
 
     /**
      * basic constructor - with bytes.
+     * @param string the byte encoding of the characters making up the string.
      */
     DERIA5String(
         byte[]   string)
@@ -78,6 +82,7 @@ public class DERIA5String
 
     /**
      * basic constructor - without validation.
+     * @param string the base string to use..
      */
     public DERIA5String(
         String   string)
@@ -163,7 +168,8 @@ public class DERIA5String
      * return true if the passed in String can be represented without
      * loss as an IA5String, false otherwise.
      *
-     * @return true if in printable set, false otherwise.
+     * @param str the string to check.
+     * @return true if character set in IA5String set, false otherwise.
      */
     public static boolean isIA5String(
         String  str)
diff --git a/core/src/main/java/org/bouncycastle/asn1/DERNumericString.java b/core/src/main/java/org/bouncycastle/asn1/DERNumericString.java
index eca4eea2..e1b1276d 100644
--- a/core/src/main/java/org/bouncycastle/asn1/DERNumericString.java
+++ b/core/src/main/java/org/bouncycastle/asn1/DERNumericString.java
@@ -17,7 +17,9 @@ public class DERNumericString
     /**
      * return a Numeric string from the passed in object
      *
+     * @param obj a DERNumericString or an object that can be converted into one.
      * @exception IllegalArgumentException if the object cannot be converted.
+     * @return a DERNumericString instance, or null
      */
     public static DERNumericString getInstance(
         Object  obj)
@@ -50,6 +52,7 @@ public class DERNumericString
      *              tagged false otherwise.
      * @exception IllegalArgumentException if the tagged object cannot
      *               be converted.
+     * @return a DERNumericString instance, or null.
      */
     public static DERNumericString getInstance(
         ASN1TaggedObject obj,
diff --git a/core/src/main/java/org/bouncycastle/asn1/DERPrintableString.java b/core/src/main/java/org/bouncycastle/asn1/DERPrintableString.java
index 9f9b3dd1..e7c5d753 100644
--- a/core/src/main/java/org/bouncycastle/asn1/DERPrintableString.java
+++ b/core/src/main/java/org/bouncycastle/asn1/DERPrintableString.java
@@ -16,8 +16,10 @@ public class DERPrintableString
 
     /**
      * return a printable string from the passed in object.
-     * 
+     *
+     * @param obj a DERPrintableString or an object that can be converted into one.
      * @exception IllegalArgumentException if the object cannot be converted.
+     * @return a DERPrintableString instance, or null.
      */
     public static DERPrintableString getInstance(
         Object  obj)
@@ -50,6 +52,7 @@ public class DERPrintableString
      *              tagged false otherwise.
      * @exception IllegalArgumentException if the tagged object cannot
      *               be converted.
+     * @return a DERPrintableString instance, or null.
      */
     public static DERPrintableString getInstance(
         ASN1TaggedObject obj,
diff --git a/core/src/main/java/org/bouncycastle/asn1/DERT61String.java b/core/src/main/java/org/bouncycastle/asn1/DERT61String.java
index d50fb7c3..783cd336 100644
--- a/core/src/main/java/org/bouncycastle/asn1/DERT61String.java
+++ b/core/src/main/java/org/bouncycastle/asn1/DERT61String.java
@@ -18,7 +18,9 @@ public class DERT61String
     /**
      * return a T61 string from the passed in object.
      *
+     * @param obj a DERT61String or an object that can be converted into one.
      * @exception IllegalArgumentException if the object cannot be converted.
+     * @return a DERT61String instance, or null
      */
     public static DERT61String getInstance(
         Object  obj)
@@ -51,6 +53,7 @@ public class DERT61String
      *              tagged false otherwise.
      * @exception IllegalArgumentException if the tagged object cannot
      *               be converted.
+     * @return a DERT61String instance, or null
      */
     public static DERT61String getInstance(
         ASN1TaggedObject obj,
@@ -70,6 +73,8 @@ public class DERT61String
 
     /**
      * basic constructor - string encoded as a sequence of bytes.
+     *
+     * @param string the byte encoding of the string to be wrapped.
      */
     public DERT61String(
         byte[]   string)
@@ -79,6 +84,8 @@ public class DERT61String
 
     /**
      * basic constructor - with string 8 bit assumed.
+     *
+     * @param string the string to be wrapped.
      */
     public DERT61String(
         String   string)