2006-01-19 Raif S. Naffah <raif@swiftdsl.com.au>

	* java/security/interfaces/RSAMultiPrimePrivateCrtKey.java: Replaced
	  what looked like proprietary documentation with original or new one.
	* java/security/spec/PSSParameterSpec.java: Likewise.
	* java/security/spec/RSAMultiPrimePrivateCrtKeySpec.java: Likewise.
	* java/security/spec/RSAOtherPrimeInfo.java: Likewise.
	* java/security/AlgorithmParameterGenerator.java: Likewise.
	* java/security/AlgorithmParameters.java: Likewise.
	* java/security/Identity.java: Likewise.
	* java/security/IdentityScope.java: Likewise.
	* java/security/KeyFactory.java: Likewise.
	* java/security/KeyPairGenerator.java: Likewise.
	* java/security/MessageDigest.java: Likewise.
	* java/security/Policy.java: Likewise.
	* java/security/ProtectionDomain.java: Likewise.
	* java/security/Security.java: Likewise.
	* java/security/Signature.java: Likewise.
	* java/security/SignatureSpi.java: Likewise.
	* java/security/SignedObject.java: Likewise.
	* java/security/Signer.java: Likewise.

18 files changed, 1511 insertions, 2067 deletions

diff --git a/java/security/AlgorithmParameterGenerator.java b/java/security/AlgorithmParameterGenerator.java
index 5dc9e3bb2..e33fbaf81 100644
--- a/java/security/AlgorithmParameterGenerator.java
+++ b/java/security/AlgorithmParameterGenerator.java
@@ -43,38 +43,15 @@ import gnu.java.security.Engine;
 import java.security.spec.AlgorithmParameterSpec;
 
 /**
- * <p>The <code>AlgorithmParameterGenerator</code> class is used to generate a
- * set of parameters to be used with a certain algorithm. Parameter generators
- * are constructed using the <code>getInstance()</code> factory methods (static
- * methods that return instances of a given class).</p>
- *
- * <p>The object that will generate the parameters can be initialized in two
- * different ways: in an algorithm-independent manner, or in an
- * algorithm-specific manner:</p>
- *
- * <ul>
- *  <li>The algorithm-independent approach uses the fact that all parameter
- *  generators share the concept of a <i>"size"</i> and a <i>source of
- *  randomness</i>. The measure of <i>size</i> is universally shared by all
- *  algorithm parameters, though it is interpreted differently for different
- *  algorithms. For example, in the case of parameters for the <i>DSA</i>
- *  algorithm, <i>"size"</i> corresponds to the size of the prime modulus (in
- *  bits). When using this approach, algorithm-specific parameter generation
- *  values - if any - default to some standard values, unless they can be
- *  derived from the specified size.</li>
- *  <li>The other approach initializes a parameter generator object using
- *  algorithm-specific semantics, which are represented by a set of
- *  algorithm-specific parameter generation values. To generate Diffie-Hellman
- *  system parameters, for example, the parameter generation values usually
- *  consist of the size of the prime modulus and the size of the random
- *  exponent, both specified in number of bits.</li>
- * </ul>
- *
+ * <code>AlgorithmParameterGenerator</code> is used to generate algorithm
+ * parameters for specified algorithms.
+ * 
  * <p>In case the client does not explicitly initialize the
- * <code>AlgorithmParameterGenerator</code> (via a call to an <code>init()</code>
- * method), each provider must supply (and document) a default initialization.
- * For example, the <b>GNU</b> provider uses a default modulus prime size of
- * <code>1024</code> bits for the generation of <i>DSA</i> parameters.
+ * <code>AlgorithmParameterGenerator</code> (via a call to an
+ * <code>init()</code> method), each provider must supply (and document) a
+ * default initialization. For example, the <b>GNU</b> provider uses a default
+ * modulus prime size of <code>1024</code> bits for the generation of <i>DSA</i>
+ * parameters.
  *
  * @author Mark Benvenuto
  * @since 1.2
@@ -92,11 +69,14 @@ public class AlgorithmParameterGenerator
   private String algorithm;
 
   /**
-   * Creates an <code>AlgorithmParameterGenerator</code> object.
-   *
-   * @param paramGenSpi the delegate.
-   * @param provider the provider.
-   * @param algorithm the algorithm.
+   * Constructs a new instance of <code>AlgorithmParameterGenerator</code>.
+   * 
+   * @param paramGenSpi
+   *          the generator to use.
+   * @param provider
+   *          the provider to use.
+   * @param algorithm
+   *          the algorithm to use.
    */
   protected AlgorithmParameterGenerator(AlgorithmParameterGeneratorSpi
 					paramGenSpi, Provider provider,
@@ -107,30 +87,21 @@ public class AlgorithmParameterGenerator
     this.algorithm = algorithm;
   }
 
-  /**
-   * Returns the standard name of the algorithm this parameter generator is
-   * associated with.
-   *
-   * @return the string name of the algorithm.
-   */
+  /** @return the name of the algorithm. */
   public final String getAlgorithm()
   {
     return algorithm;
   }
 
   /**
-   * Generates an <code>AlgorithmParameterGenerator</code> object that
-   * implements the specified digest algorithm. If the default provider package
-   * provides an implementation of the requested digest algorithm, an instance
-   * of <code>AlgorithmParameterGenerator</code> containing that implementation
-   * is returned. If the algorithm is not available in the default package,
-   * other packages are searched.
-   *
-   * @param algorithm the string name of the algorithm this parameter generator
-   * is associated with.
-   * @return the new <code>AlgorithmParameterGenerator</code> object.
-   * @throws NoSuchAlgorithmException if the algorithm is not available in the
-   * environment.
+   * Returns a new <code>AlgorithmParameterGenerator</code> instance which
+   * generates algorithm parameters for the specified algorithm.
+   * 
+   * @param algorithm
+   *          the name of algorithm to use.
+   * @return the new instance.
+   * @throws NoSuchAlgorithmException
+   *           if <code>algorithm</code> is not implemented by any provider.
    */
   public static AlgorithmParameterGenerator getInstance(String algorithm)
     throws NoSuchAlgorithmException
@@ -150,20 +121,18 @@ public class AlgorithmParameterGenerator
   }
 
   /**
-   * Generates an <code>AlgorithmParameterGenerator</code> object for the
-   * requested algorithm, as supplied from the specified provider, if such a
-   * parameter generator is available from the provider.
-   *
-   * @param algorithm the string name of the algorithm.
-   * @param provider the string name of the provider.
-   * @return the new <code>AlgorithmParameterGenerator</code> object.
-   * @throws NoSuchAlgorithmException if the <code>algorithm</code> is not
-   * available from the <code>provider</code>.
-   * @throws NoSuchProviderException if the <code>provider</code> is not
-   * available in the environment.
-   * @throws IllegalArgumentException if the <code>provider</code> name is
-   * <code>null</code> or empty.
-   * @see Provider
+   * Returns a new <code>AlgorithmParameterGenerator</code> instance which
+   * generates algorithm parameters for the specified algorithm.
+   * 
+   * @param algorithm
+   *          the name of algorithm to use.
+   * @param provider
+   *          the name of the {@link Provider} to use.
+   * @return the new instance.
+   * @throws NoSuchAlgorithmException
+   *           if the algorithm is not implemented by the named provider.
+   * @throws NoSuchProviderException
+   *           if the named provider was not found.
    */
   public static AlgorithmParameterGenerator getInstance(String algorithm,
 							String provider)
@@ -180,17 +149,16 @@ public class AlgorithmParameterGenerator
   }
 
   /**
-   * Generates an AlgorithmParameterGenerator object for the requested
-   * algorithm, as supplied from the specified provider, if such a parameter
-   * generator is available from the provider. Note: the <code>provider</code>
-   * doesn't have to be registered.
-   *
-   * @param algorithm the string name of the algorithm.
-   * @param provider the provider.
-   * @return the new AlgorithmParameterGenerator object.
-   * @throws NoSuchAlgorithmException if the algorithm is not available from
-   * the provider.
-   * @throws IllegalArgumentException if the provider is null.
+   * Returns a new <code>AlgorithmParameterGenerator</code> instance which
+   * generates algorithm parameters for the specified algorithm.
+   * 
+   * @param algorithm
+   *          the name of algorithm to use.
+   * @param provider
+   *          the {@link Provider} to use.
+   * @return the new instance.
+   * @throws NoSuchAlgorithmException
+   *           if the algorithm is not implemented by {@link Provider}.
    * @since 1.4
    * @see Provider
    */
@@ -218,24 +186,18 @@ public class AlgorithmParameterGenerator
       }
   }
 
-  /**
-   * Returns the provider of this algorithm parameter generator object.
-   *
-   * @return the provider of this algorithm parameter generator object.
-   */
+  /** @return the {@link Provider} of this generator. */
   public final Provider getProvider()
   {
     return provider;
   }
 
   /**
-   * Initializes this parameter generator for a certain <i>size</i>. To create
-   * the parameters, the {@link SecureRandom} implementation of the
-   * highest-priority installed provider is used as the source of randomness.
-   * (If none of the installed providers supply an implementation of
-   * {@link SecureRandom}, a system-provided source of randomness is used.)
-   *
-   * @param size the size (number of bits).
+   * Initializes this instance with the specified size. Since no source of
+   * randomness is supplied, a default one will be used.
+   * 
+   * @param size
+   *          size (in bits) to use.
    */
   public final void init(int size)
   {
@@ -243,11 +205,13 @@ public class AlgorithmParameterGenerator
   }
 
   /**
-   * Initializes this parameter generator for a certain size and source of
+   * Initializes this instance with the specified key-size and source of
    * randomness.
-   *
-   * @param size the size (number of bits).
-   * @param random the source of randomness.
+   * 
+   * @param size
+   *          the size (in bits) to use.
+   * @param random
+   *          the {@link SecureRandom} to use.
    */
   public final void init(int size, SecureRandom random)
   {
@@ -255,33 +219,30 @@ public class AlgorithmParameterGenerator
   }
 
   /**
-   * Initializes this parameter generator with a set of algorithm-specific
-   * parameter generation values. To generate the parameters, the {@link
-   * SecureRandom} implementation of the highest-priority installed provider is
-   * used as the source of randomness. (If none of the installed providers
-   * supply an implementation of {@link SecureRandom}, a system-provided source
-   * of randomness is used.)
-   *
-   * @param genParamSpec the set of algorithm-specific parameter generation
-   * values.
-   * @throws InvalidAlgorithmParameterException if the given parameter
-   * generation values are inappropriate for this parameter generator.
+   * Initializes this instance with the specified {@link AlgorithmParameterSpec}.
+   * Since no source of randomness is supplied, a default one will be used.
+   * 
+   * @param genParamSpec
+   *          the {@link AlgorithmParameterSpec} to use.
+   * @throws InvalidAlgorithmParameterException
+   *           if <code>genParamSpec</code> is invalid.
    */
   public final void init(AlgorithmParameterSpec genParamSpec)
-    throws InvalidAlgorithmParameterException
+      throws InvalidAlgorithmParameterException
   {
     init(genParamSpec, new SecureRandom());
   }
 
   /**
-   * Initializes this parameter generator with a set of algorithm-specific
-   * parameter generation values.
-   *
-   * @param genParamSpec the set of algorithm-specific parameter generation
-   * values.
-   * @param random the source of randomness.
-   * @throws InvalidAlgorithmParameterException if the given parameter
-   * generation values are inappropriate for this parameter generator.
+   * Initializes this instance with the specified {@link AlgorithmParameterSpec}
+   * and source of randomness.
+   * 
+   * @param genParamSpec
+   *          the {@link AlgorithmParameterSpec} to use.
+   * @param random
+   *          the {@link SecureRandom} to use.
+   * @throws InvalidAlgorithmParameterException
+   *           if <code>genParamSpec</code> is invalid.
    */
   public final void init(AlgorithmParameterSpec genParamSpec,
                          SecureRandom random)
@@ -290,11 +251,7 @@ public class AlgorithmParameterGenerator
     paramGenSpi.engineInit(genParamSpec, random);
   }
 
-  /**
-   * Generates the parameters.
-   *
-   * @return the new {@link AlgorithmParameters} object.
-   */
+  /** @return a new instance of {@link AlgorithmParameters}. */
   public final AlgorithmParameters generateParameters()
   {
     return paramGenSpi.engineGenerateParameters();
diff --git a/java/security/AlgorithmParameters.java b/java/security/AlgorithmParameters.java
index 038fbb4bd..c4655aefa 100644
--- a/java/security/AlgorithmParameters.java
+++ b/java/security/AlgorithmParameters.java
@@ -45,36 +45,9 @@ import java.security.spec.AlgorithmParameterSpec;
 import java.security.spec.InvalidParameterSpecException;
 
 /**
- * <p>This class is used as an opaque representation of cryptographic
- * parameters.</p>
- *
- * <p>An <code>AlgorithmParameters</code> object for managing the parameters
- * for a particular algorithm can be obtained by calling one of the
- * <code>getInstance()</code> factory methods (static methods that return
- * instances of a given class).</p>
- *
- * <p>There are two ways to request such an implementation: by specifying
- * either just an algorithm name, or both an algorithm name and a package
- * provider.</p>
- *
- * <ul>
- *    <li>If just an algorithm name is specified, the system will determine if
- *    there is an AlgorithmParameters implementation for the algorithm requested
- *    available in the environment, and if there is more than one, if there is
- *    a preferred one.</li>
- *    <li>If both an algorithm name and a package provider are specified, the
- *    system will determine if there is an implementation in the package
- *    requested, and throw an exception if there is not.</li>
- * </ul>
- *
- * <p>Once an <code>AlgorithmParameters</code> object is returned, it must be
- * initialized via a call to <code>init()</code>, using an appropriate
- * parameter specification or parameter encoding.</p>
- *
- * <p>A transparent parameter specification is obtained from an
- * <code>AlgorithmParameters</code> object via a call to
- * <code>getParameterSpec()</code>, and a byte encoding of the parameters is
- * obtained via a call to <code>getEncoded()</code>.</p>
+ * <code>AlgorithmParameters</code> is an Algorithm Parameters class which
+ * provides an interface through which the user can manage the parameters of an
+ * Algorithm.
  *
  * @author Mark Benvenuto
  * @since 1.2
@@ -92,11 +65,14 @@ public class AlgorithmParameters
   private String algorithm;
 
   /**
-   * Creates an <code>AlgorithmParameters</code> object.
-   *
-   * @param paramSpi the delegate.
-   * @param provider the provider.
-   * @param algorithm the algorithm.
+   * Constructs a new instance of <code>AlgorithmParameters</code>.
+   * 
+   * @param paramSpi
+   *          the engine to use.
+   * @param provider
+   *          the provider to use.
+   * @param algorithm
+   *          the algorithm to use.
    */
   protected AlgorithmParameters(AlgorithmParametersSpi paramSpi,
                                 Provider provider, String algorithm)
@@ -106,32 +82,24 @@ public class AlgorithmParameters
     this.algorithm = algorithm;
   }
 
-  /**
-   * Returns the name of the algorithm associated with this parameter object.
-   *
-   * @return the algorithm name.
-   */
+  /** @return A string with the name of the algorithm used. */
   public final String getAlgorithm()
   {
     return algorithm;
   }
 
   /**
-   * <p>Generates a parameter object for the specified algorithm.</p>
-   *
-   * <p>If the default provider package provides an implementation of the
-   * requested algorithm, an instance of <code>AlgorithmParameters</code>
-   * containing that implementation is returned. If the algorithm is not
-   * available in the default package, other packages are searched.</p>
-   *
-   * <p>The returned parameter object must be initialized via a call to
-   * <code>init()</code>, using an appropriate parameter specification or
-   * parameter encoding.</p>
-   *
-   * @param algorithm the name of the algorithm requested.
-   * @return the new parameter object.
-   * @throws NoSuchAlgorithmException if the algorithm is not available in the
-   * environment.
+   * Returns a new instance of <code>AlgorithmParameters</code> representing
+   * the specified algorithm parameters.
+   * 
+   * <p>The returned <code>AlgorithmParameters</code> must still be initialized
+   * with an <code>init()</code> method.</p>
+   * 
+   * @param algorithm
+   *          the algorithm to use.
+   * @return the new instance repesenting the desired algorithm.
+   * @throws NoSuchAlgorithmException
+   *           if the algorithm is not implemented by any provider.
    */
   public static AlgorithmParameters getInstance(String algorithm)
     throws NoSuchAlgorithmException
@@ -152,23 +120,24 @@ public class AlgorithmParameters
   }
 
   /**
-   * <p>Generates a parameter object for the specified algorithm, as supplied
-   * by the specified provider, if such an algorithm is available from the
-   * provider.</p>
-   *
-   * <p>The returned parameter object must be initialized via a call to
-   * <code>init()</code>, using an appropriate parameter specification or
-   * parameter encoding.</p>
-   *
-   * @param algorithm the name of the algorithm requested.
-   * @param provider the name of the provider.
-   * @return the new parameter object.
-   * @throws NoSuchAlgorithmException if the algorithm is not available in the
-   * package supplied by the requested provider.
-   * @throws NoSuchProviderException if the provider is not available in the
-   * environment.
-   * @throws IllegalArgumentException if the provider name is null or empty.
-   * @see Provider
+   * Returns a new instance of <code>AlgorithmParameters</code> representing
+   * the specified algorithm parameters from a named provider.
+   * 
+   * <p>The returned <code>AlgorithmParameters</code> must still be intialized
+   * with an <code>init()</code> method.</p>
+   * 
+   * @param algorithm
+   *          the algorithm to use.
+   * @param provider
+   *          the name of the {@link Provider} to use.
+   * @return the new instance repesenting the desired algorithm.
+   * @throws NoSuchAlgorithmException
+   *           if the algorithm is not implemented by the named provider.
+   * @throws NoSuchProviderException
+   *           if the named provider was not found.
+   * @throws IllegalArgumentException
+   *           if <code>provider</code> is <code>null</code> or is an empty
+   *           string.
    */
   public static AlgorithmParameters getInstance(String algorithm, String provider)
     throws NoSuchAlgorithmException, NoSuchProviderException
@@ -184,18 +153,21 @@ public class AlgorithmParameters
   }
 
   /**
-   * Generates an <code>AlgorithmParameterGenerator</code> object for the
-   * requested algorithm, as supplied from the specified provider, if such a
-   * parameter generator is available from the provider. Note: the
-   * <code>provider</code> doesn't have to be registered.
-   *
-   * @param algorithm the string name of the algorithm.
-   * @param provider the provider.
-   * @return the new <code>AlgorithmParameterGenerator</code> object.
-   * @throws NoSuchAlgorithmException if the <code>algorithm</code> is not
-   * available from the <code>provider</code>.
-   * @throws IllegalArgumentException if the <code>provider</code> is
-   * <code>null</code>.
+   * Returns a new instance of <code>AlgorithmParameters</code> representing
+   * the specified algorithm parameters from the specified {@link Provider}.
+   * 
+   * <p>The returned <code>AlgorithmParameters</code> must still be intialized
+   * with an <code>init()</code> method.</p>
+   * 
+   * @param algorithm
+   *          the algorithm to use.
+   * @param provider
+   *          the {@link Provider} to use.
+   * @return the new instance repesenting the desired algorithm.
+   * @throws NoSuchAlgorithmException
+   *           if the algorithm is not implemented by the {@link Provider}.
+   * @throws IllegalArgumentException
+   *           if <code>provider</code> is <code>null</code>.
    * @since 1.4
    */
   public static AlgorithmParameters getInstance(String algorithm,
@@ -221,24 +193,19 @@ public class AlgorithmParameters
       }
   }
 
-  /**
-   * Returns the provider of this parameter object.
-   *
-   * @return the provider of this parameter object.
-   */
+  /** @return the provider of this parameter object. */
   public final Provider getProvider()
   {
     return provider;
   }
 
   /**
-   * Initializes this parameter object using the parameters specified in
-   * <code>paramSpec</code>.
-   *
-   * @param paramSpec the parameter specification.
-   * @throws InvalidParameterSpecException if the given parameter specification
-   * is inappropriate for the initialization of this parameter object, or if
-   * this parameter object has already been initialized.
+   * Initializes the engine with the specified {@link AlgorithmParameterSpec}.
+   * 
+   * @param paramSpec
+   *          A {@link AlgorithmParameterSpec} to use.
+   * @throws InvalidParameterSpecException
+   *           if <code>paramSpec</code> is invalid.
    */
   public final void init(AlgorithmParameterSpec paramSpec)
     throws InvalidParameterSpecException
@@ -247,13 +214,15 @@ public class AlgorithmParameters
   }
 
   /**
-   * Imports the specified parameters and decodes them according to the primary
-   * decoding format for parameters. The primary decoding format for parameters
-   * is ASN.1, if an ASN.1 specification for this type of parameters exists.
-   *
-   * @param params the encoded parameters.
-   * @throws IOException on decoding errors, or if this parameter object has
-   * already been initialized.
+   * Initializes the engine with the specified parameters stored in the byte
+   * array and decodes them according to the ASN.1 specification. If the ASN.1
+   * specification exists then it succeeds otherwise an {@link IOException} is
+   * thrown.
+   * 
+   * @param params
+   *          the parameters to use.
+   * @throws IOException
+   *           if a decoding error occurs.
    */
   public final void init(byte[]params) throws IOException
   {
@@ -261,15 +230,18 @@ public class AlgorithmParameters
   }
 
   /**
-   * Imports the parameters from params and decodes them according to the
-   * specified decoding scheme. If <code>format</code> is <code>null</code>,
-   * the primary decoding format for parameters is used. The primary decoding
-   * format is ASN.1, if an ASN.1 specification for these parameters exists.
-   *
-   * @param params the encoded parameters.
-   * @param format the name of the decoding scheme.
-   * @throws IOException on decoding errors, or if this parameter object has
-   * already been initialized.
+   * Initializes the engine with the specified parameters stored in the byte
+   * array and decodes them according to the specified decoding specification.
+   * If <code>format</code> is <code>null</code>, then this method decodes the
+   * byte array using the ASN.1 specification if it exists, otherwise it throws
+   * an {@link IOException}.
+   * 
+   * @param params
+   *          the parameters to use.
+   * @param format
+   *          the name of decoding format to use.
+   * @throws IOException
+   *           if a decoding error occurs.
    */
   public final void init(byte[]params, String format) throws IOException
   {
@@ -277,19 +249,14 @@ public class AlgorithmParameters
   }
 
   /**
-   * Returns a (transparent) specification of this parameter object.
-   * <code>paramSpec</code> identifies the specification class in which the
-   * parameters should be returned. It could, for example, be
-   * <code>DSAParameterSpec.class</code>, to indicate that the parameters should
-   * be returned in an instance of the {@link java.security.spec.DSAParameterSpec}
-   * class.
-   *
-   * @param paramSpec the specification class in which the parameters should be
-   * returned.
+   * Returns a new instance of <code>AlgorithmParameters</code> as a
+   * designated parameter specification {@link Class}.
+   * 
+   * @param paramSpec
+   *          the {@link Class} to use.
    * @return the parameter specification.
-   * @throws InvalidParameterSpecException if the requested parameter
-   * specification is inappropriate for this parameter object, or if this
-   * parameter object has not been initialized.
+   * @throws InvalidParameterSpecException
+   *           if <code>paramSpec</code> is invalid.
    */
   public final AlgorithmParameterSpec getParameterSpec(Class paramSpec)
     throws InvalidParameterSpecException
@@ -298,13 +265,10 @@ public class AlgorithmParameters
   }
 
   /**
-   * Returns the parameters in their primary encoding format. The primary
-   * encoding format for parameters is ASN.1, if an ASN.1 specification for
-   * this type of parameters exists.
-   *
-   * @return the parameters encoded using their primary encoding format.
-   * @throws IOException on encoding errors, or if this parameter object has not
-   * been initialized.
+   * Returns the parameters in the default encoding format. The primary encoding
+   * format is ASN.1 if it exists for the specified type.
+   * 
+   * @return byte array representing the parameters.
    */
   public final byte[] getEncoded() throws IOException
   {
@@ -312,15 +276,16 @@ public class AlgorithmParameters
   }
 
   /**
-   * Returns the parameters encoded in the specified scheme. If format is
-   * <code>null</code>, the primary encoding format for parameters is used. The
-   * primary encoding format is ASN.1, if an ASN.1 specification for these
-   * parameters exists.
-   *
-   * @param format the name of the encoding format.
+   * Returns the parameters in the specified encoding format. If
+   * <code>format</code> is <code>null</code> then the ASN.1 encoding
+   * format is used if it exists for the specified type.
+   * 
+   * @param format
+   *          the name of the encoding format to use.
    * @return the parameters encoded using the specified encoding scheme.
-   * @throws IOException on encoding errors, or if this parameter object has
-   * not been initialized.
+   * @throws IOException
+   *           if an encoding exception occurs, or if this parameter object has
+   *           not been initialized.
    */
   public final byte[] getEncoded(String format) throws IOException
   {
@@ -328,10 +293,9 @@ public class AlgorithmParameters
   }
 
   /**
-   * Returns a formatted string describing the parameters.
-   *
-   * @return a formatted string describing the parameters, or <code>null</code>
-   * if this parameter object has not been initialized.
+   * Returns a string representation of the encoded form.
+   * 
+   * @return a string representation of the encoded form.
    */
   public final String toString()
   {
diff --git a/java/security/Identity.java b/java/security/Identity.java
index 7ef59cfe2..c9df0a58f 100644
--- a/java/security/Identity.java
+++ b/java/security/Identity.java
@@ -41,31 +41,27 @@ import java.io.Serializable;
 import java.util.Vector;
 
 /**
- * <p>This class represents identities: real-world objects such as people,
- * companies or organizations whose identities can be authenticated using their
- * public keys. Identities may also be more abstract (or concrete) constructs,
- * such as daemon threads or smart cards.</p>
- *
- * <p>All Identity objects have a <i>name</i> and a <i>public key</i>. Names
- * are immutable. <i>Identities</i> may also be <b>scoped</b>. That is, if an
- * <i>Identity</i> is specified to have a particular <i>scope</i>, then the
- * <i>name</i> and <i>public key</i> of the <i>Identity</i> are unique within
- * that <i>scope</i>.</p>
- *
- * <p>An <i>Identity</i> also has a <i>set of certificates</i> (all certifying
- * its own <i>public key</i>). The <i>Principal</i> names specified in these
- * certificates need not be the same, only the key.</p>
- *
- * <p>An <i>Identity</i> can be subclassed, to include postal and email
- * addresses, telephone numbers, images of faces and logos, and so on.</p>
+ * The <code>Identity</code> class is used to represent people and companies
+ * that can be authenticated using public key encryption. The identities can
+ * also be abstract objects such as smart cards.
+ * 
+ * <p><code>Identity</code> objects store a name and public key for each
+ * identity. The names cannot be changed and the identities can be scoped. Each
+ * identity (name and public key) within a scope are unique to that scope.</p>
+ * 
+ * <p>Each identity has a set of ceritificates which all specify the same
+ * public key, but not necessarily the same name.</p>
+ * 
+ * <p>The <code>Identity</code> class can be subclassed to allow additional
+ * information to be attached to it.</p>
  *
  * @author Mark Benvenuto
  * @see IdentityScope
  * @see Signer
  * @see Principal
- * @deprecated This class is no longer used. Its functionality has been replaced
- * by <code>java.security.KeyStore</code>, the <code>java.security.cert</code>
- * package, and <code>java.security.Principal</code>.
+ * @deprecated Replaced by <code>java.security.KeyStore</code>, the
+ * <code>java.security.cert</code> package, and
+ * <code>java.security.Principal</code>.
  */
 public abstract class Identity implements Principal, Serializable
 {
@@ -83,12 +79,15 @@ public abstract class Identity implements Principal, Serializable
   }
 
   /**
-   * Constructs an identity with the specified name and scope.
-   *
-   * @param name the identity name.
-   * @param scope the scope of the identity.
-   * @throws KeyManagementException if there is already an identity with the
-   * same name in the scope.
+   * Constructs a new instance of <code>Identity</code> with the specified
+   * name and scope.
+   * 
+   * @param name
+   *          the name to use.
+   * @param scope
+   *          the scope to use.
+   * @throws KeyManagementException
+   *           if the identity is already present.
    */
   public Identity(String name, IdentityScope scope)
     throws KeyManagementException
@@ -98,9 +97,11 @@ public abstract class Identity implements Principal, Serializable
   }
 
   /**
-   * Constructs an identity with the specified name and no scope.
-   *
-   * @param name the identity name.
+   * Constructs a new instance of <code>Identity</code> with the specified
+   * name and no scope.
+   * 
+   * @param name
+   *          the name to use.
    */
   public Identity(String name)
   {
@@ -108,30 +109,20 @@ public abstract class Identity implements Principal, Serializable
     this.scope = null;
   }
 
-  /**
-   * Returns this identity's name.
-   *
-   * @return the name of this identity.
-   */
+  /** @return the name of this identity. */
   public final String getName()
   {
     return name;
   }
 
-  /**
-   * Returns this identity's scope.
-   *
-   * @return the scope of this identity.
-   */
+  /** @return the scope of this identity. */
   public final IdentityScope getScope()
   {
     return scope;
   }
 
   /**
-   * Returns this identity's public key.
-   *
-   * @return the public key for this identity.
+   * @return the public key of this identity.
    * @see #setPublicKey(java.security.PublicKey)
    */
   public PublicKey getPublicKey()
@@ -140,21 +131,17 @@ public abstract class Identity implements Principal, Serializable
   }
 
   /**
-   * <p>Sets this identity's public key. The old key and all of this identity's
-   * certificates are removed by this operation.</p>
-   *
-   * <p>First, if there is a security manager, its <code>checkSecurityAccess()
-   * </code> method is called with <code>"setIdentityPublicKey"</code> as its
-   * argument to see if it's ok to set the public key.</p>
-   *
-   * @param key the public key for this identity.
-   * @throws KeyManagementException if another identity in the identity's scope
-   * has the same public key, or if another exception occurs.
-   * @throws SecurityException if a security manager exists and its
-   * <code>checkSecurityAccess()</code> method doesn't allow setting the public
-   * key.
-   * @see #getPublicKey()
-   * @see SecurityManager#checkSecurityAccess(String)
+   * Sets the public key for this identity. The old key and all certificates
+   * are removed.
+   * 
+   * @param key
+   *          the public key to use.
+   * @throws KeyManagementException
+   *           if this public key is used by another identity in the current
+   *           scope.
+   * @throws SecurityException
+   *           if a {@link SecurityManager} is installed which disallows this
+   *           operation.
    */
   public void setPublicKey(PublicKey key) throws KeyManagementException
   {
@@ -166,18 +153,13 @@ public abstract class Identity implements Principal, Serializable
   }
 
   /**
-   * <p>Specifies a general information string for this identity.</p>
-   *
-   * <p>First, if there is a security manager, its <code>checkSecurityAccess()
-   * </code> method is called with <code>"setIdentityInfo"</code> as its
-   * argument to see if it's ok to specify the information string.</p>
-   *
-   * @param info the information string.
-   * @throws SecurityException if a security manager exists and its
-   * <code>checkSecurityAccess()</code> method doesn't allow setting the
-   * information string.
-   * @see #getInfo()
-   * @see SecurityManager#checkSecurityAccess(String)
+   * Sets the general information string.
+   * 
+   * @param info
+   *          the general information string.
+   * @throws SecurityException
+   *           if a {@link SecurityManager} is installed which disallows this
+   *           operation.
    */
   public void setInfo(String info)
   {
@@ -189,9 +171,7 @@ public abstract class Identity implements Principal, Serializable
   }
 
   /**
-   * Returns general information previously specified for this identity.
-   *
-   * @return general information about this identity.
+   * @return the general information string of this identity.
    * @see #setInfo(String)
    */
   public String getInfo()
@@ -200,23 +180,17 @@ public abstract class Identity implements Principal, Serializable
   }
 
   /**
-   * <p>Adds a certificate for this identity. If the identity has a public key,
-   * the public key in the certificate must be the same, and if the identity
-   * does not have a public key, the identity's public key is set to be that
-   * specified in the certificate.</p>
-   *
-   * <p>First, if there is a security manager, its <code>checkSecurityAccess()
-   * </code> method is called with <code>"addIdentityCertificate"</code> as its
-   * argument to see if it's ok to add a certificate.</p>
-   *
-   * @param certificate the certificate to be added.
-   * @throws KeyManagementException if the certificate is not valid, if the
-   * public key in the certificate being added conflicts with this identity's
-   * public key, or if another exception occurs.
-   * @throws SecurityException if a security manager exists and its
-   * <code>checkSecurityAccess()</code> method doesn't allow adding a
-   * certificate.
-   * @see SecurityManager#checkSecurityAccess(String)
+   * Adds a certificate to the list of ceritificates for this identity. The
+   * public key in this certificate must match the existing public key if it
+   * exists.
+   * 
+   * @param certificate
+   *          the certificate to add.
+   * @throws KeyManagementException
+   *           if the certificate is invalid, or the public key conflicts.
+   * @throws SecurityException
+   *           if a {@link SecurityManager} is installed which disallows this
+   *           operation.
    */
   public void addCertificate(Certificate certificate)
     throws KeyManagementException
@@ -235,19 +209,15 @@ public abstract class Identity implements Principal, Serializable
   }
 
   /**
-   * <p>Removes a certificate from this identity.</p>
-   *
-   * <p>First, if there is a security manager, its <code>checkSecurityAccess()
-   * </code> method is called with <code>"removeIdentityCertificate"</code> as
-   * its argument to see if it's ok to remove a certificate.</p>
-   *
-   * @param certificate the certificate to be removed.
-   * @throws KeyManagementException if the certificate is missing, or if
-   * another exception occurs.
-   * @throws SecurityException if a security manager exists and its
-   * <code>checkSecurityAccess()</code> method doesn't allow removing a
-   * certificate.
-   * @see SecurityManager#checkSecurityAccess(String)
+   * Removes a certificate from the list of ceritificates for this identity.
+   * 
+   * @param certificate
+   *          the certificate to remove.
+   * @throws KeyManagementException
+   *           if the certificate is invalid.
+   * @throws SecurityException
+   *           if a {@link SecurityManager} is installed which disallows this
+   *           operation.
    */
   public void removeCertificate(Certificate certificate)
     throws KeyManagementException
@@ -262,11 +232,7 @@ public abstract class Identity implements Principal, Serializable
     certificates.removeElement(certificate);
   }
 
-  /**
-   * Returns a copy of all the certificates for this identity.
-   *
-   * @return a copy of all the certificates for this identity.
-   */
+  /** @return an array of {@link Certificate}s for this identity. */
   public Certificate[] certificates()
   {
     Certificate[] certs = new Certificate[certificates.size()];
@@ -278,17 +244,13 @@ public abstract class Identity implements Principal, Serializable
   }
 
   /**
-   * Tests for equality between the specified object and this identity. This
-   * first tests to see if the entities actually refer to the same object, in
-   * which case it returns <code>true</code>. Next, it checks to see if the
-   * entities have the same <i>name</i> and the same <i>scope</i>. If they do,
-   * the method returns <code>true</code>. Otherwise, it calls
-   * <code>identityEquals()</code>, which subclasses should override.
-   *
-   * @param identity the object to test for equality with this identity.
-   * @return <code>true</code> if the objects are considered equal, <code>false
-   * </code>otherwise.
-   * @see #identityEquals(Identity)
+   * Checks for equality between this Identity and a specified object. It first
+   * checks if they are the same object, then if the name and scope match and
+   * returns <code>true</code> if successful. If these tests fail, the
+   * {@link #identityEquals(Identity)} method is called.
+   * 
+   * @return <code>true</code> if they are equal, <code>false</code>
+   *         otherwise.
    */
   public final boolean equals(Object identity)
   {
@@ -307,15 +269,12 @@ public abstract class Identity implements Principal, Serializable
   }
 
   /**
-   * Tests for equality between the specified <code>identity</code> and this
-   * <i>identity</i>. This method should be overriden by subclasses to test for
-   * equality. The default behavior is to return <code>true</code> if the names
-   * and public keys are equal.
-   *
-   * @param identity the identity to test for equality with this identity.
-   * @return <code>true</code> if the identities are considered equal,
-   * <code>false</code> otherwise.
-   * @see #equals(Object)
+   * Checks for equality between this Identity and a specified object. A
+   * subclass should override this method. The default behavior is to return
+   * <code>true</code> if the public key and names match.
+   * 
+   * @return <code>true</code> if they are equal, <code>false</code>
+   *         otherwise.
    */
   protected boolean identityEquals(Identity identity)
   {
@@ -324,19 +283,12 @@ public abstract class Identity implements Principal, Serializable
   }
 
   /**
-   * <p>Returns a short string describing this identity, telling its name and
-   * its scope (if any).</p>
-   *
-   * <p>First, if there is a security manager, its <code>checkSecurityAccess()
-   * </code> method is called with <code>"printIdentity"</code> as its argument
-   * to see if it's ok to return the string.</p>
-   *
-   * @return information about this identity, such as its name and the name of
-   * its scope (if any).
-   * @throws SecurityException if a security manager exists and its
-   * <code>checkSecurityAccess()</code> method doesn't allow returning a string
-   * describing this identity.
-   * @see SecurityManager#checkSecurityAccess(String)
+   * Returns a string representation of this Identity.
+   * 
+   * @return a string representation of this Identity.
+   * @throws SecurityException
+   *           if a {@link SecurityManager} is installed which disallows this
+   *           operation.
    */
   public String toString()
   {
@@ -349,23 +301,14 @@ public abstract class Identity implements Principal, Serializable
   }
 
   /**
-   * <p>Returns a string representation of this identity, with optionally more
-   * details than that provided by the <code>toString()</code> method without
-   * any arguments.</p>
-   *
-   * <p>First, if there is a security manager, its <code>checkSecurityAccess()
-   * </code> method is called with <code>"printIdentity"</code> as its argument
-   * to see if it's ok to return the string.</p>
-   *
-   * @param detailed whether or not to provide detailed information.
-   * @return information about this identity. If detailed is <code>true</code>,
-   * then this method returns more information than that provided by the
-   * <code>toString()</code> method without any arguments.
-   * @throws SecurityException if a security manager exists and its
-   * <code>checkSecurityAccess()</code> method doesn't allow returning a string
-   * describing this identity.
-   * @see #toString()
-   * @see SecurityManager#checkSecurityAccess(String)
+   * Returns a detailed string representation of this Identity.
+   * 
+   * @param detailed
+   *          indicates whether or detailed information is desired.
+   * @return a string representation of this Identity.
+   * @throws SecurityException
+   *           if a {@link SecurityManager} is installed which disallows this
+   *           operation.
    */
   public String toString(boolean detailed)
   {
@@ -385,11 +328,7 @@ public abstract class Identity implements Principal, Serializable
       }
   }
 
-  /**
-   * Returns a hashcode for this identity.
-   *
-   * @return a hashcode for this identity.
-   */
+  /** @return a hashcode of this identity. */
   public int hashCode()
   {
     int ret = name.hashCode();
diff --git a/java/security/IdentityScope.java b/java/security/IdentityScope.java
index 34dd011e2..d1ea1f295 100644
--- a/java/security/IdentityScope.java
+++ b/java/security/IdentityScope.java
@@ -40,52 +40,42 @@ package java.security;
 import java.util.Enumeration;
 
 /**
- * <p>This class represents a scope for identities. It is an Identity itself,
- * and therefore has a name and can have a scope. It can also optionally have a
- * public key and associated certificates.</p>
- *
- * <p>An <code>IdentityScope</code> can contain {@link Identity} objects of all
- * kinds, including {@link Signer}s. All types of <code>Identity</code> objects
- * can be retrieved, added, and removed using the same methods. Note that it is
- * possible, and in fact expected, that different types of identity scopes will
- * apply different policies for their various operations on the various types of
+ * <code>IdentityScope</code> represents a scope of an identity.
+ * <code>IdentityScope</code> is also an {@link Identity} and can have a name
+ * and scope along with the other qualitites identities possess.
+ * 
+ * <p>An <code>IdentityScope</code> contains other {@link Identity} objects.
+ * All {@link Identity} objects are manipulated in the scope the same way. The
+ * scope is supposed to apply different scope to different type of
  * Identities.</p>
- *
- * <p>There is a one-to-one mapping between keys and identities, and there can
- * only be one copy of one key per scope. For example, suppose Acme Software,
- * Inc is a software publisher known to a user. Suppose it is an <i>Identity</i>,
- * that is, it has a public key, and a set of associated certificates. It is
- * named in the scope using the name "Acme Software". No other named <i>Identity
- * </i> in the scope has the same public key. Of course, none has the same name
- * as well.</p>
- *
+ * 
+ * <p>No identity within the same scope can have the same public key.</p>
+ * 
  * @author Mark Benvenuto
  * @see Identity
  * @see Signer
  * @see Principal
  * @see Key
- * @deprecated This class is no longer used. Its functionality has been replaced
- * by <code>java.security.KeyStore</code>, the <code>java.security.cert</code>
- * package, and <code>java.security.Principal</code>.
+ * @deprecated Use java.security.KeyStore, the java.security.cert package, and
+ *             java.security.Principal.
  */
 public abstract class IdentityScope extends Identity
 {
   private static final long serialVersionUID = -2337346281189773310L;
   private static IdentityScope systemScope;
 
-  /**
-   * This constructor is used for serialization only and should not be used by
-   * subclasses.
-   */
+  /** Constructor for serialization purposes. */
   protected IdentityScope()
   {
     super();
   }
 
   /**
-   * Constructs a new identity scope with the specified name.
-   *
-   * @param name the scope name.
+   * Constructs a new instance of <code>IdentityScope</code> with the
+   * specified name and no scope.
+   * 
+   * @param name
+   *          the name to use.
    */
   public IdentityScope(String name)
   {
@@ -93,12 +83,15 @@ public abstract class IdentityScope extends Identity
   }
 
   /**
-   * Constructs a new identity scope with the specified name and scope.
-   *
-   * @param name the scope name.
-   * @param scope the scope for the new identity scope.
-   * @throws KeyManagementException if there is already an identity with the
-   * same name in the scope.
+   * Constructs a new instance of <code>IdentityScope</code> with the
+   * specified name and {@link IdentityScope}.
+   * 
+   * @param name
+   *          the name to use.
+   * @param scope
+   *          the scope to use.
+   * @throws KeyManagementException
+   *           if the identity scope is already present.
    */
   public IdentityScope(String name, IdentityScope scope)
     throws KeyManagementException
@@ -107,10 +100,9 @@ public abstract class IdentityScope extends Identity
   }
 
   /**
-   * Returns the system's identity scope.
-   *
-   * @return the system's identity scope.
-   * @see #setSystemScope(IdentityScope)
+   * Returns the system's Scope.
+   * 
+   * @return the system's Scope.
    */
   public static IdentityScope getSystemScope()
   {
@@ -123,18 +115,13 @@ public abstract class IdentityScope extends Identity
   }
 
   /**
-   * Sets the system's identity scope.
-   *
-   * <p>First, if there is a security manager, its <code>checkSecurityAccess()
-   * </code> method is called with <code>"setSystemScope"</code> as its argument
-   * to see if it's ok to set the identity scope.</p>
-   *
-   * @param scope the scope to set.
-   * @throws SecurityException if a security manager exists and its
-   * <code>checkSecurityAccess()</code> method doesn't allow setting the
-   * identity scope.
-   * @see #getSystemScope()
-   * @see SecurityManager#checkSecurityAccess(String)
+   * Sets the scope of the system.
+   * 
+   * @param scope
+   *          the new system scope.
+   * @throws SecurityException
+   *           if a {@link SecurityManager} is installed which disallows this
+   *           operation.
    */
   protected static void setSystemScope(IdentityScope scope)
   {
@@ -146,29 +133,30 @@ public abstract class IdentityScope extends Identity
   }
 
   /**
-   * Returns the number of identities within this identity scope.
-   *
-   * @return the number of identities within this identity scope.
+   * Returns the number of entries within this <code>IdentityScope</code>.
+   * 
+   * @return the number of entries within this <code>IdentityScope</code>.
    */
   public abstract int size();
 
   /**
-   * Returns the identity in this scope with the specified name (if any).
-   *
-   * @param name the name of the identity to be retrieved.
-   * @return the identity named name, or <code>null</code> if there are no
-   * identities named name in this scope.
+   * Returns the specified {@link Identity}, by name, within this scope.
+   * 
+   * @param name
+   *          name of {@link Identity} to get.
+   * @return an {@link Identity} representing the name or <code>null</code> if
+   *         it cannot be found.
    */
   public abstract Identity getIdentity(String name);
 
   /**
-   * Retrieves the identity whose name is the same as that of the specified
-   * principal. (Note: <code>Identity</code> implements <code>Principal</code>.)
-   *
-   * @param principal the principal corresponding to the identity to be
-   * retrieved.
-   * @return the identity whose name is the same as that of the principal, or
-   * <code>null</code> if there are no identities of the same name in this scope.
+   * Returns the specified {@link Identity}, by {@link Principal}, within this
+   * scope.
+   * 
+   * @param principal
+   *          the {@link Principal} to use.
+   * @return an identity representing the {@link Principal} or <code>null</code>
+   *         if it cannot be found.
    */
   public Identity getIdentity(Principal principal)
   {
@@ -176,48 +164,50 @@ public abstract class IdentityScope extends Identity
   }
 
   /**
-   * Retrieves the identity with the specified public key.
-   *
-   * @param key the public key for the identity to be returned.
-   * @return the identity with the given key, or <code>null</code> if there are
-   * no identities in this scope with that key.
+   * Returns the specified {@link Identity}, by public key, within this scope.
+   * 
+   * @param key
+   *          the {@link PublicKey} to use.
+   * @return an identity representing the public key or <code>null</code> if
+   *         it cannot be found.
    */
   public abstract Identity getIdentity(PublicKey key);
 
   /**
-   * Adds an identity to this identity scope.
-   *
-   * @param identity the identity to be added.
-   * @throws KeyManagementException if the identity is not valid, a name
-   * conflict occurs, another identity has the same public key as the identity
-   * being added, or another exception occurs.
+   * Adds an identity to his scope.
+   * 
+   * @param identity
+   *          the {@link Identity} to add.
+   * @throws KeyManagementException
+   *           if it is an invalid identity, an identity with the same key
+   *           exists, or if another error occurs.
    */
   public abstract void addIdentity(Identity identity)
     throws KeyManagementException;
 
   /**
-   * Removes an identity from this identity scope.
-   *
-   * @param identity the identity to be removed.
-   * @throws KeyManagementException if the identity is missing, or another
-   * exception occurs.
+   * Removes an identity in this scope.
+   * 
+   * @param identity
+   *          the {@link Identity} to remove.
+   * @throws KeyManagementException
+   *           if it is a missing identity, or if another error occurs.
    */
   public abstract void removeIdentity(Identity identity)
     throws KeyManagementException;
 
   /**
-   * Returns an enumeration of all identities in this identity scope.
-   *
-   * @return an enumeration of all identities in this identity scope.
+   * Returns an {@link Enumeration} of identities in this scope.
+   * 
+   * @return an {@link Enumeration} of the identities in this scope.
    */
   public abstract Enumeration identities();
 
   /**
-   * Returns a string representation of this identity scope, including its name,
-   * its scope name, and the number of identities in this identity scope.
-   *
-   * @return a string representation of this identity scope.
-   * @see SecurityManager#checkSecurityAccess(String)
+   * Returns a string representing this instance. It includes the name, the
+   * scope name, and number of identities.
+   * 
+   * @return a string representation of this instance.
    */
   public String toString()
   {
diff --git a/java/security/KeyFactory.java b/java/security/KeyFactory.java
index 64ce841fa..edb2a87da 100644
--- a/java/security/KeyFactory.java
+++ b/java/security/KeyFactory.java
@@ -44,40 +44,18 @@ import java.security.spec.InvalidKeySpecException;
 import java.security.spec.KeySpec;
 
 /**
- * <p>Key factories are used to convert keys (opaque cryptographic keys of type
+ * Key factories are used to convert keys (opaque cryptographic keys of type
  * {@link Key}) into key specifications (transparent representations of the
- * underlying key material), and vice versa.</p>
- *
- * <p>Key factories are bi-directional. That is, they allow you to build an
- * opaque key object from a given key specification (key material), or to
- * retrieve the underlying key material of a key object in a suitable format.</p>
- *
- * <p>Multiple compatible key specifications may exist for the same key. For
- * example, a <i>DSA</i> public key may be specified using {@link
- * java.security.spec.DSAPublicKeySpec} or {@link
- * java.security.spec.X509EncodedKeySpec}. A key factory can be used to
- * translate between compatible key specifications.</p>
- *
- * <p>The following is an example of how to use a key factory in order to
- * instantiate a <i>DSA</i> public key from its encoding. Assume Alice has
- * received a digital signature from Bob. Bob also sent her his public key (in
- * encoded format) to verify his signature. Alice then performs the following
- * actions:
- *
- * <pre>
- *  X509EncodedKeySpec bobPubKeySpec = new X509EncodedKeySpec(bobEncodedPubKey);
- *  KeyFactory keyFactory = KeyFactory.getInstance("DSA");
- *  PublicKey bobPubKey = keyFactory.generatePublic(bobPubKeySpec);
- *  Signature sig = Signature.getInstance("DSA");
- *  sig.initVerify(bobPubKey);
- *  sig.update(data);
- *  sig.verify(signature);
- * </pre>
+ * underlying key material).
+ * 
+ * <p>Key factories are bi-directional. They allow a key class to be converted
+ * into a key specification (key material) and back again. For example DSA
+ * public keys can be specified as <code>DSAPublicKeySpec</code> or
+ * <code>X509EncodedKeySpec</code>. A key factory translates these key
+ * specifications.</p>
  *
  * @since 1.2
  * @see Key
- * @see PublicKey
- * @see PrivateKey
  * @see KeySpec
  * @see java.security.spec.DSAPublicKeySpec
  * @see java.security.spec.X509EncodedKeySpec
@@ -93,12 +71,15 @@ public class KeyFactory
   private String algorithm;
 
   /**
-   * Creates a <code>KeyFactory</code> object.
-   *
-   * @param keyFacSpi the delegate.
-   * @param provider the provider.
-   * @param algorithm the name of the algorithm to associate with this
-   * <code>KeyFactory</code>.
+   * Constructs a new instance of <code>KeyFactory</code> with the specified
+   * parameters.
+   * 
+   * @param keyFacSpi
+   *          the key factory to use.
+   * @param provider
+   *          the provider to use.
+   * @param algorithm
+   *          the name of the key algorithm to use.
    */
   protected KeyFactory(KeyFactorySpi keyFacSpi, Provider provider,
 		       String algorithm)
@@ -109,19 +90,14 @@ public class KeyFactory
   }
 
   /**
-   * Generates a <code>KeyFactory</code> object that implements the specified
-   * algorithm. If the default provider package provides an implementation of
-   * the requested algorithm, an instance of <code>KeyFactory</code> containing
-   * that implementation is returned. If the algorithm is not available in the
-   * default package, other packages are searched.
-   *
-   * @param algorithm the name of the requested key algorithm. See Appendix A
-   * in the Java Cryptography Architecture API Specification &amp; Reference
-   * for information about standard algorithm names.
-   * @return a <code>KeyFactory</code> object for the specified algorithm.
-   * @throws NoSuchAlgorithmException if the requested algorithm is not
-   * available in the default provider package or any of the other provider
-   * packages that were searched.
+   * Returns a new instance of <code>KeyFactory</code> representing the
+   * specified key factory.
+   * 
+   * @param algorithm
+   *          the name of algorithm to use.
+   * @return a new instance repesenting the desired algorithm.
+   * @throws NoSuchAlgorithmException
+   *           if the algorithm is not implemented by any provider.
    */
   public static KeyFactory getInstance(String algorithm)
     throws NoSuchAlgorithmException
@@ -141,19 +117,21 @@ public class KeyFactory
   }
 
   /**
-   * Generates a <code>KeyFactory</code> object for the specified algorithm
-   * from the specified provider.
-   *
-   * @param algorithm the name of the requested key algorithm. See Appendix A
-   * in the Java Cryptography Architecture API Specification &amp; Reference
-   * for information about standard algorithm names.
-   * @param provider the name of the provider.
-   * @return a <code>KeyFactory</code> object for the specified algorithm.
-   * @throws NoSuchAlgorithmException if the algorithm is not available from
-   * the specified provider.
-   * @throws NoSuchProviderException if the provider has not been configured.
-   * @throws IllegalArgumentException if the provider name is null or empty.
-   * @see Provider
+   * Returns a new instance of <code>KeyFactory</code> representing the
+   * specified key factory from the specified provider.
+   * 
+   * @param algorithm
+   *          the name of algorithm to use.
+   * @param provider
+   *          the name of the provider to use.
+   * @return a new instance repesenting the desired algorithm.
+   * @throws IllegalArgumentException
+   *           if <code>provider</code> is <code>null</code> or is an empty
+   *           string.
+   * @throws NoSuchAlgorithmException
+   *           if the algorithm is not implemented by the named provider.
+   * @throws NoSuchProviderException
+   *           if the named provider was not found.
    */
   public static KeyFactory getInstance(String algorithm, String provider)
     throws NoSuchAlgorithmException, NoSuchProviderException
@@ -169,19 +147,18 @@ public class KeyFactory
   }
 
   /**
-   * Generates a <code>KeyFactory</code> object for the specified algorithm from
-   * the specified provider. Note: the <code>provider</code> doesn't have to be
-   * registered.
-   *
-   * @param algorithm the name of the requested key algorithm. See Appendix A
-   * in the Java Cryptography Architecture API Specification &amp; Reference for
-   * information about standard algorithm names.
-   * @param provider the provider.
-   * @return a <code>KeyFactory</code> object for the specified algorithm.
-   * @throws NoSuchAlgorithmException if the algorithm is not available from
-   * the specified provider.
-   * @throws IllegalArgumentException if the <code>provider</code> is
-   * <code>null</code>.
+   * Returns a new instance of <code>KeyFactory</code> representing the
+   * specified key factory from the designated {@link Provider}.
+   * 
+   * @param algorithm
+   *          the name of algorithm to use.
+   * @param provider
+   *          the {@link Provider} to use.
+   * @return a new instance repesenting the desired algorithm.
+   * @throws IllegalArgumentException
+   *           if <code>provider</code> is <code>null</code>.
+   * @throws NoSuchAlgorithmException
+   *           if the algorithm is not implemented by {@link Provider}.
    * @since 1.4
    * @see Provider
    */
@@ -208,9 +185,9 @@ public class KeyFactory
   }
 
   /**
-   * Returns the provider of this key factory object.
-   *
-   * @return the provider of this key factory object.
+   * Returns the {@link Provider} of this instance.
+   * 
+   * @return the {@link Provider} of this instance.
    */
   public final Provider getProvider()
   {
@@ -218,10 +195,9 @@ public class KeyFactory
   }
 
   /**
-   * Gets the name of the algorithm associated with this <code>KeyFactory</code>.
-   *
-   * @return the name of the algorithm associated with this
-   * <code>KeyFactory</code>.
+   * Returns the name of the algorithm used.
+   * 
+   * @return the name of the algorithm used.
    */
   public final String getAlgorithm()
   {
@@ -229,13 +205,13 @@ public class KeyFactory
   }
 
   /**
-   * Generates a public key object from the provided key specification (key
-   * material).
-   *
-   * @param keySpec the specification (key material) of the public key.
+   * Generates a public key from the provided key specification.
+   * 
+   * @param keySpec
+   *          the key specification.
    * @return the public key.
-   * @throws InvalidKeySpecException if the given key specification is
-   * inappropriate for this key factory to produce a public key.
+   * @throws InvalidKeySpecException
+   *           if the key specification is invalid.
    */
   public final PublicKey generatePublic(KeySpec keySpec)
     throws InvalidKeySpecException
@@ -244,13 +220,13 @@ public class KeyFactory
   }
 
   /**
-   * Generates a private key object from the provided key specification (key
-   * material).
-   *
-   * @param keySpec the specification (key material) of the private key.
+   * Generates a private key from the provided key specification.
+   * 
+   * @param keySpec
+   *          the key specification.
    * @return the private key.
-   * @throws InvalidKeySpecException if the given key specification is
-   * inappropriate for this key factory to produce a private key.
+   * @throws InvalidKeySpecException
+   *           if the key specification is invalid.
    */
   public final PrivateKey generatePrivate(KeySpec keySpec)
     throws InvalidKeySpecException
@@ -259,21 +235,18 @@ public class KeyFactory
   }
 
   /**
-   * Returns a specification (key material) of the given key object.
-   * <code>keySpec</code> identifies the specification class in which the key
-   * material should be returned. It could, for example, be
-   * <code>DSAPublicKeySpec.class</code>, to indicate that the key material
-   * should be returned in an instance of the {@link
-   * java.security.spec.DSAPublicKeySpec} class.
-   *
-   * @param key the key.
-   * @param keySpec the specification class in which the key material should be
-   * returned.
-   * @return the underlying key specification (key material) in an instance of
-   * the requested specification class.
-   * @throws InvalidKeySpecException if the requested key specification is
-   * inappropriate for the given key, or the given key cannot be processed
-   * (e.g., the given key has an unrecognized algorithm or format).
+   * Returns a key specification for the given key. <code>keySpec</code>
+   * identifies the specification class to return the key material in.
+   * 
+   * @param key
+   *          the key to use.
+   * @param keySpec
+   *          the specification class to use.
+   * @return the key specification in an instance of the requested specification
+   *         class.
+   * @throws InvalidKeySpecException
+   *           the requested key specification is inappropriate for this key or
+   *           the key is unrecognized.
    */
   public final KeySpec getKeySpec(Key key, Class keySpec)
     throws InvalidKeySpecException
@@ -282,13 +255,14 @@ public class KeyFactory
   }
 
   /**
-   * Translates a key object, whose provider may be unknown or potentially
-   * untrusted, into a corresponding key object of this key factory.
-   *
-   * @param key the key whose provider is unknown or untrusted.
+   * Translates the key from an unknown or untrusted provider into a key from
+   * this key factory.
+   * 
+   * @param key
+   *          the key to translate from.
    * @return the translated key.
-   * @throws InvalidKeyException if the given key cannot be processed by this
-   * key factory.
+   * @throws InvalidKeyException
+   *           if the key cannot be processed by this key factory.
    */
   public final Key translateKey(Key key) throws InvalidKeyException
   {
diff --git a/java/security/KeyPairGenerator.java b/java/security/KeyPairGenerator.java
index a6e010be2..bd1fe680b 100644
--- a/java/security/KeyPairGenerator.java
+++ b/java/security/KeyPairGenerator.java
@@ -43,72 +43,14 @@ import gnu.java.security.Engine;
 import java.security.spec.AlgorithmParameterSpec;
 
 /**
- * <p>The <code>KeyPairGenerator</code> class is used to generate pairs of
- * public and private keys. Key pair generators are constructed using the
- * <code>getInstance()</code> factory methods (static methods that return
- * instances of a given class).</p>
+ * <code>KeyPairGenerator</code> is a class used to generate key-pairs for a
+ * security algorithm.
+ * 
+ * <p>The <code>KeyPairGenerator</code> is created with the
+ * <code>getInstance()</code> Factory methods. It is used to generate a pair of
+ * public and private keys for a specific algorithm and associate this key-pair
+ * with the algorithm parameters it was initialized with.</p>
  *
- * <p>A Key pair generator for a particular algorithm creates a public/private
- * key pair that can be used with this algorithm. It also associates
- * algorithm-specific parameters with each of the generated keys.</p>
- *
- * <p>There are two ways to generate a key pair: in an algorithm-independent
- * manner, and in an algorithm-specific manner. The only difference between the
- * two is the initialization of the object:</p>
- *
- * <ul>
- * <li><b>Algorithm-Independent Initialization</b><br/>
- *     All key pair generators share the concepts of a <i>keysize</i> and a
- *     <i>source of randomness</i>. The <i>keysize</i> is interpreted differently
- *     for different algorithms (e.g., in the case of the <i>DSA</i> algorithm,
- *     the <i>keysize</i> corresponds to the length of the modulus). There is an
- *     <code>initialize()</code> method in this <code>KeyPairGenerator</code>
- *     class that takes these two universally shared types of arguments. There
- *     is also one that takes just a <i>keysize</i> argument, and uses the
- *     {@link SecureRandom} implementation of the highest-priority installed
- *     provider as the <i>source of randomness</i>. (If none of the installed
- *     providers supply an implementation of {@link SecureRandom}, a
- *     system-provided source of randomness is used.)
- *
- *     <p>Since no other parameters are specified when you call the above
- *     algorithm-independent initialize methods, it is up to the provider what
- *     to do about the algorithm-specific parameters (if any) to be associated
- *     with each of the keys.</p>
- *
- *     <p>If the algorithm is the <i>DSA</i> algorithm, and the <i>keysize</i>
- *     (modulus size) is <code>512</code>, <code>768</code>, or <code>1024</code>,
- *     then the <b>GNU</b> provider uses a set of precomputed values for the
- *     <code>p</code>, <code>q</code>, and <code>g</code> parameters. If the
- *     <i>modulus size</i> is not one of the above values, the <b>GNU</b>
- *     provider creates a new set of parameters. Other providers might have
- *     precomputed parameter sets for more than just the three modulus sizes
- *     mentioned above. Still others might not have a list of precomputed
- *     parameters at all and instead always create new parameter sets.</p></li>
- * <li><b>Algorithm-Specific Initialization</b><br/>
- *     For situations where a set of algorithm-specific parameters already
- *     exists (e.g., so-called <i>community parameters</i> in <i>DSA</i>), there
- *     are two initialize methods that have an {@link AlgorithmParameterSpec}
- *     argument. One also has a {@link SecureRandom} argument, while the the
- *     other uses the {@link SecureRandom} implementation of the highest-priority
- *     installed provider as the source of randomness. (If none of the installed
- *     providers supply an implementation of {@link SecureRandom}, a
- *     system-provided source of randomness is used.)</li>
- * </ul>
- *
- * <p>In case the client does not explicitly initialize the
- * <code>KeyPairGenerator</code> (via a call to an initialize method), each
- * provider must supply (and document) a default initialization. For example,
- * the <b>GNU</b> provider uses a default modulus size (keysize) of
- * <code>1024</code> bits.</p>
- *
- * <p>Note that this class is abstract and extends from {@link
- * KeyPairGeneratorSpi} for historical reasons. Application developers should
- * only take notice of the methods defined in this <code>KeyPairGenerator</code>
- * class; all the methods in the superclass are intended for cryptographic
- * service providers who wish to supply their own implementations of key pair
- * generators.</p>
- *
- * @see Signature
  * @see KeyPair
  * @see AlgorithmParameterSpec
  * @author Mark Benvenuto
@@ -123,13 +65,10 @@ public abstract class KeyPairGenerator extends KeyPairGeneratorSpi
   private String algorithm;
 
   /**
-   * Creates a <code>KeyPairGenerator</code> object for the specified 
-   * algorithm.
-   *
-   * @param algorithm the standard string name of the algorithm. 
-   * See Appendix A in the Java Cryptography Architecture API 
-   * Specification &amp; Reference for information about standard 
-   * algorithm names.
+   * Constructs a new instance of <code>KeyPairGenerator</code>.
+   * 
+   * @param algorithm
+   *          the algorithm to use.
    */
   protected KeyPairGenerator(String algorithm)
   {
@@ -138,11 +77,9 @@ public abstract class KeyPairGenerator extends KeyPairGeneratorSpi
   }
 
   /**
-   * Returns the standard name of the algorithm for this key pair generator.
-   * See Appendix A in the Java Cryptography Architecture API Specification
-   * &amp; Reference for information about standard algorithm names.
-   *
-   * @return the standard string name of the algorithm.
+   * Returns the name of the algorithm used.
+   * 
+   * @return the name of the algorithm used.
    */
   public String getAlgorithm()
   {
@@ -150,19 +87,14 @@ public abstract class KeyPairGenerator extends KeyPairGeneratorSpi
   }
 
   /**
-   * Generates a <code>KeyPairGenerator</code> object that implements the
-   * specified digest algorithm. If the default provider package provides an
-   * implementation of the requested digest algorithm, an instance of
-   * <code>KeyPairGenerator</code> containing that implementation is returned.
-   * If the algorithm is not available in the default package, other packages
-   * are searched.
-   *
-   * @param algorithm the standard string name of the algorithm. See Appendix A
-   * in the Java Cryptography Architecture API Specification &amp; Reference for
-   * information about standard algorithm names.
-   * @return the new <code>KeyPairGenerator</code> object.
-   * @throws NoSuchAlgorithmException if the algorithm is not available in the
-   * environment.
+   * Returns a new instance of <code>KeyPairGenerator</code> which generates
+   * key-pairs for the specified algorithm.
+   * 
+   * @param algorithm
+   *          the name of the algorithm to use.
+   * @return a new instance repesenting the desired algorithm.
+   * @throws NoSuchAlgorithmException
+   *           if the algorithm is not implemented by any provider.
    */
   public static KeyPairGenerator getInstance(String algorithm)
     throws NoSuchAlgorithmException
@@ -184,22 +116,18 @@ public abstract class KeyPairGenerator extends KeyPairGeneratorSpi
   }
 
   /**
-   * Generates a <code>KeyPairGenerator</code> object implementing the 
-   * specified algorithm, as supplied from the specified provider, if 
-   * such an algorithm is available from the provider.
-   *
-   * @param algorithm the standard string name of the algorithm. See 
-   * Appendix A in the Java Cryptography Architecture API Specification 
-   * &amp; Reference for information about standard algorithm names.
-   * @param provider the string name of the provider.
-   * @return the new <code>KeyPairGenerator</code> object.
-   * @throws NoSuchAlgorithmException if the algorithm is not available 
-   * from the provider.
-   * @throws NoSuchProviderException if the provider is not available in the
-   * environment.
-   * @throws IllegalArgumentException if the provider name is <code>null</code>
-   * or empty.
-   * @see Provider
+   * Returns a new instance of <code>KeyPairGenerator</code> which generates
+   * key-pairs for the specified algorithm from a named provider.
+   * 
+   * @param algorithm
+   *          the name of the algorithm to use.
+   * @param provider
+   *          the name of a {@link Provider} to use.
+   * @return a new instance repesenting the desired algorithm.
+   * @throws NoSuchAlgorithmException
+   *           if the algorithm is not implemented by the named provider.
+   * @throws NoSuchProviderException
+   *           if the named provider was not found.
    */
   public static KeyPairGenerator getInstance(String algorithm, String provider)
     throws NoSuchAlgorithmException, NoSuchProviderException
@@ -212,20 +140,18 @@ public abstract class KeyPairGenerator extends KeyPairGeneratorSpi
   }
 
   /**
-   * Generates a <code>KeyPairGenerator</code> object implementing the specified
-   * algorithm, as supplied from the specified provider, if such an algorithm is
-   * available from the provider. Note: the provider doesn't have to be
-   * registered.
-   *
-   * @param algorithm the standard string name of the algorithm. See Appendix A
-   * in the Java Cryptography Architecture API Specification &amp; Reference for
-   * information about standard algorithm names.
-   * @param provider the provider.
-   * @return the new <code>KeyPairGenerator</code> object.
-   * @throws NoSuchAlgorithmException if the <code>algorithm</code> is not
-   * available from the <code>provider</code>.
-   * @throws IllegalArgumentException if the <code>provider</code> is
-   * <code>null</code>.
+   * Returns a new instance of <code>KeyPairGenerator</code> which generates
+   * key-pairs for the specified algorithm from a designated {@link Provider}.
+   * 
+   * @param algorithm
+   *          the name of the algorithm to use.
+   * @param provider
+   *          the {@link Provider} to use.
+   * @return a new insatnce repesenting the desired algorithm.
+   * @throws IllegalArgumentException
+   *           if <code>provider</code> is <code>null</code>.
+   * @throws NoSuchAlgorithmException
+   *           if the algorithm is not implemented by the {@link Provider}.
    * @since 1.4
    * @see Provider
    */
@@ -261,9 +187,9 @@ public abstract class KeyPairGenerator extends KeyPairGeneratorSpi
   }
 
   /**
-   * Returns the provider of this key pair generator object.
-   *
-   * @return the provider of this key pair generator object.
+   * Returns the {@link Provider} of this instance.
+   * 
+   * @return the {@link Provider} of this instance.
    */
   public final Provider getProvider()
   {
@@ -271,16 +197,11 @@ public abstract class KeyPairGenerator extends KeyPairGeneratorSpi
   }
 
   /**
-   * Initializes the key pair generator for a certain keysize using a default
-   * parameter set and the {@link SecureRandom} implementation of the
-   * highest-priority installed provider as the source of randomness. (If none
-   * of the installed providers supply an implementation of {@link SecureRandom},
-   * a system-provided source of randomness is used.)
-   *
-   * @param keysize the keysize. This is an algorithm-specific metric, such as
-   * modulus length, specified in number of bits.
-   * @throws InvalidParameterException if the keysize is not supported by this
-   * <code>KeyPairGenerator</code> object.
+   * Initializes this instance for the specified key size. Since no source of
+   * randomness is specified, a default one will be used.
+   * 
+   * @param keysize
+   *          the size of keys to use.
    */
   public void initialize(int keysize)
   {
@@ -288,14 +209,13 @@ public abstract class KeyPairGenerator extends KeyPairGeneratorSpi
   }
 
   /**
-   * Initializes the key pair generator for a certain keysize with the given
-   * source of randomness (and a default parameter set).
-   *
-   * @param keysize the keysize. This is an algorithm-specific metric, such as
-   * modulus length, specified in number of bits.
-   * @param random the source of randomness.
-   * @throws InvalidParameterException if the <code>keysize</code> is not
-   * supported by this <code>KeyPairGenerator</code> object.
+   * Initializes this instance for the specified key size and
+   * {@link SecureRandom}.
+   * 
+   * @param keysize
+   *          the size of keys to use.
+   * @param random
+   *          the {@link SecureRandom} to use.
    * @since 1.2
    */
   public void initialize(int keysize, SecureRandom random)
@@ -303,24 +223,14 @@ public abstract class KeyPairGenerator extends KeyPairGeneratorSpi
   }
 
   /**
-   * <p>Initializes the key pair generator using the specified parameter set and
-   * the {@link SecureRandom} implementation of the highest-priority installed
-   * provider as the source of randomness. (If none of the installed providers
-   * supply an implementation of {@link SecureRandom}, a system-provided source
-   * of randomness is used.)</p>
-   *
-   * <p>This concrete method has been added to this previously-defined abstract
-   * class. This method calls the
-   * {@link KeyPairGeneratorSpi#initialize(AlgorithmParameterSpec, SecureRandom)}
-   * initialize method, passing it <code>params</code> and a source of
-   * randomness (obtained from the highest-priority installed provider or
-   * system-provided if none of the installed providers supply one). That
-   * initialize method always throws an {@link UnsupportedOperationException}
-   * if it is not overridden by the provider.</p>
-   *
-   * @param params the parameter set used to generate the keys.
-   * @throws InvalidAlgorithmParameterException if the given parameters are
-   * inappropriate for this key pair generator.
+   * Initializes this instance with the specified
+   * {@link AlgorithmParameterSpec}. Since no source of randomness is specified,
+   * a default one will be used.
+   * 
+   * @param params
+   *          the {@link AlgorithmParameterSpec} to use.
+   * @throws InvalidAlgorithmParameterException
+   *           if the designated specifications are invalid.
    * @since 1.2
    */
   public void initialize(AlgorithmParameterSpec params)
@@ -330,20 +240,15 @@ public abstract class KeyPairGenerator extends KeyPairGeneratorSpi
   }
 
   /**
-   * <p>Initializes the key pair generator with the given parameter set and
-   * source of randomness.</p>
-   *
-   * <p>This concrete method has been added to this previously-defined abstract
-   * class. This method calls the
-   * {@link KeyPairGeneratorSpi#initialize(AlgorithmParameterSpec, SecureRandom)}
-   * initialize method, passing it <code>params</code> and <code>random</code>.
-   * That initialize method always throws an {@link UnsupportedOperationException}
-   * if it is not overridden by the provider.</p>
-   *
-   * @param params the parameter set used to generate the keys.
-   * @param random the source of randomness.
-   * @throws InvalidAlgorithmParameterException if the given parameters are
-   * inappropriate for this key pair generator.
+   * Initializes this instance with the specified {@link AlgorithmParameterSpec}
+   * and {@link SecureRandom}.
+   * 
+   * @param params
+   *          the {@link AlgorithmParameterSpec} to use.
+   * @param random
+   *          the {@link SecureRandom} to use.
+   * @throws InvalidAlgorithmParameterException
+   *           if the designated specifications are invalid.
    * @since 1.2
    */
   public void initialize(AlgorithmParameterSpec params, SecureRandom random)
@@ -353,17 +258,12 @@ public abstract class KeyPairGenerator extends KeyPairGeneratorSpi
   }
 
   /**
-   * <p>Generates a key pair.</p>
-   *
-   * <p>If this <code>KeyPairGenerator</code> has not been initialized
-   * explicitly, provider-specific defaults will be used for the size and other
-   * (algorithm-specific) values of the generated keys.</p>
-   *
-   * <p>This will generate a new key pair every time it is called.</p>
-   *
-   * <p>This method is functionally equivalent to {@link #generateKeyPair()}.</p>
-   *
-   * @return the generated key pair.
+   * Generates a new "DSA" {@link KeyPair} from the "GNU" security provider.
+   * 
+   * <p>This method generates a unique key-pair each time it is called.</p>
+   * 
+   * @return a new unique {@link KeyPair}.
+   * @see #generateKeyPair()
    * @since 1.2
    */
   public final KeyPair genKeyPair()
@@ -381,17 +281,12 @@ public abstract class KeyPairGenerator extends KeyPairGeneratorSpi
   }
 
   /**
-   * <p>Generates a key pair.</p>
-   *
-   * <p>If this <code>KeyPairGenerator</code> has not been initialized
-   * explicitly, provider-specific defaults will be used for the size and other
-   * (algorithm-specific) values of the generated keys.</p>
-   *
-   * <p>This will generate a new key pair every time it is called.</p>
-   *
-   * <p>This method is functionally equivalent to {@link #genKeyPair()}.</p>
-   *
-   * @return the generated key pair.
+   * Generates a new "DSA" {@link KeyPair} from the "GNU" security provider.
+   * 
+   * <p>This method generates a unique key pair each time it is called.</p>
+   * 
+   * @return a new unique {@link KeyPair}.
+   * @see #genKeyPair()
    */
   public KeyPair generateKeyPair()
   {
diff --git a/java/security/MessageDigest.java b/java/security/MessageDigest.java
index 8a6af645b..b817759f5 100644
--- a/java/security/MessageDigest.java
+++ b/java/security/MessageDigest.java
@@ -40,54 +40,10 @@ package java.security;
 import gnu.java.security.Engine;
 
 /**
- * <p>This <code>MessageDigest</code> class provides applications the
- * functionality of a message digest algorithm, such as <i>MD5</i> or <i>SHA</i>.
  * Message digests are secure one-way hash functions that take arbitrary-sized
- * data and output a fixed-length hash value.</p>
- *
- * <p>A <code>MessageDigest</code> object starts out initialized. The data is
- * processed through it using the <code>update()</code> methods. At any point
- * <code>reset()</code> can be called to reset the digest. Once all the data to
- * be updated has been updated, one of the <code>digest()</code> methods should
- * be called to complete the hash computation.</p>
- *
- * <p>The <code>digest()</code> method can be called <b>once</b> for a given
- * number of updates. After <code>digest()</code> has been called, the
- * <code>MessageDigest</code> object is <b>reset</b> to its initialized state.
- * </p>
- *
- * <p>Implementations are free to implement the {@link Cloneable} interface.
- * Client applications can test cloneability by attempting cloning and catching
- * the {@link CloneNotSupportedException}:
- *
- * <pre>
- *    MessageDigest md = MessageDigest.getInstance("SHA");
- *    try
- *      {
- *        md.update(toChapter1);
- *        MessageDigest tc1 = md.clone();
- *        byte[] toChapter1Digest = tc1.digest();
- *        md.update(toChapter2);
- *        // ...
- *      }
- *    catch (CloneNotSupportedException x)
- *      {
- *        throw new DigestException("couldn't make digest of partial content");
- *      }
- * </pre>
- *
- * <p>Note that if a given implementation is not cloneable, it is still possible
- * to compute intermediate digests by instantiating several instances, if the
- * number of digests is known in advance.</p>
- *
- * <p>Note that this class is abstract and extends from {@link MessageDigestSpi}
- * for historical reasons. Application developers should only take notice of the
- * methods defined in this <code>MessageDigest</code> class; all the methods in
- * the superclass are intended for cryptographic service providers who wish to
- * supply their own implementations of message digest algorithms.</p>
+ * data and output a fixed-length hash value.
  *
  * @see MessageDigestSpi
- * @see Provider
  * @since JDK 1.1
  */
 public abstract class MessageDigest extends MessageDigestSpi
@@ -100,12 +56,11 @@ public abstract class MessageDigest extends MessageDigestSpi
   private byte[] lastDigest;
 
   /**
-   * Creates a message digest with the specified algorithm name.
-   *
-   * @param algorithm the standard name of the digest algorithm.
-   * See Appendix A in the Java Cryptography Architecture API
-   * Specification &amp; Reference for information about standard
-   * algorithm names.
+   * Constructs a new instance of <code>MessageDigest</code> representing the
+   * specified algorithm.
+   * 
+   * @param algorithm
+   *          the name of the digest algorithm to use.
    */
   protected MessageDigest(String algorithm)
   {
@@ -114,19 +69,14 @@ public abstract class MessageDigest extends MessageDigestSpi
   }
 
   /**
-   * Generates a <code>MessageDigest</code> object that implements the specified
-   * digest algorithm. If the default provider package provides an
-   * implementation of the requested digest algorithm, an instance of
-   * <code>MessageDigest</code> containing that implementation is returned. If
-   * the algorithm is not available in the default package, other packages are
-   * searched.
-   *
-   * @param algorithm the name of the algorithm requested. See Appendix A in the
-   * Java Cryptography Architecture API Specification &amp; Reference for
-   * information about standard algorithm names.
-   * @return a Message Digest object implementing the specified algorithm.
-   * @throws NoSuchAlgorithmException if the algorithm is not available in the
-   * caller's environment.
+   * Returns a new instance of <code>MessageDigest</code> representing the
+   * specified algorithm.
+   * 
+   * @param algorithm
+   *          the name of the digest algorithm to use.
+   * @return a new instance representing the desired algorithm.
+   * @throws NoSuchAlgorithmException
+   *           if the algorithm is not implemented by any provider.
    */
   public static MessageDigest getInstance(String algorithm)
     throws NoSuchAlgorithmException
@@ -148,21 +98,18 @@ public abstract class MessageDigest extends MessageDigestSpi
   }
 
   /**
-   * Generates a <code>MessageDigest</code> object implementing the specified
-   * algorithm, as supplied from the specified provider, if such an algorithm is
-   * available from the provider.
-   *
-   * @param algorithm the name of the algorithm requested. See Appendix A in the
-   * Java Cryptography Architecture API Specification &amp; Reference for
-   * information about standard algorithm names.
-   * @param provider the name of the provider.
-   * @return a Message Digest object implementing the specified algorithm.
-   * @throws NoSuchAlgorithmException if the algorithm is not available in the
-   * package supplied by the requested provider.
-   * @throws NoSuchProviderException if the provider is not available in the
-   * environment.
-   * @throws IllegalArgumentException if the provider name is null or empty.
-   * @see Provider
+   * Returns a new instance of <code>MessageDigest</code> representing the
+   * specified algorithm from a named provider.
+   * 
+   * @param algorithm
+   *          the name of the digest algorithm to use.
+   * @param provider
+   *          the name of the provider to use.
+   * @return a new instance representing the desired algorithm.
+   * @throws NoSuchAlgorithmException
+   *           if the algorithm is not implemented by the named provider.
+   * @throws NoSuchProviderException
+   *           if the named provider was not found.
    */
   public static MessageDigest getInstance(String algorithm, String provider)
     throws NoSuchAlgorithmException, NoSuchProviderException
@@ -181,20 +128,18 @@ public abstract class MessageDigest extends MessageDigestSpi
   }
 
   /**
-   * Generates a <code>MessageDigest</code> object implementing the specified
-   * algorithm, as supplied from the specified provider, if such an algorithm
-   * is available from the provider. Note: the provider doesn't have to be
-   * registered.
-   *
-   * @param algorithm the name of the algorithm requested. See Appendix A in
-   * the Java Cryptography Architecture API Specification &amp; Reference for
-   * information about standard algorithm names.
-   * @param provider the provider.
-   * @return a Message Digest object implementing the specified algorithm.
-   * @throws NoSuchAlgorithmException if the <code>algorithm</code> is not
-   * available in the package supplied by the requested <code>provider</code>.
-   * @throws IllegalArgumentException if the <code>provider</code> is
-   * <code>null</code>.
+   * Returns a new instance of <code>MessageDigest</code> representing the
+   * specified algorithm from a designated {@link Provider}.
+   * 
+   * @param algorithm
+   *          the name of the digest algorithm to use.
+   * @param provider
+   *          the {@link Provider} to use.
+   * @return a new instance representing the desired algorithm.
+   * @throws IllegalArgumentException
+   *           if <code>provider</code> is <code>null</code>.
+   * @throws NoSuchAlgorithmException
+   *           if the algorithm is not implemented by {@link Provider}.
    * @since 1.4
    * @see Provider
    */
@@ -233,9 +178,9 @@ public abstract class MessageDigest extends MessageDigestSpi
   }
 
   /**
-   * Returns the provider of this message digest object.
-   *
-   * @return the provider of this message digest object.
+   * Returns the {@link Provider} of this instance.
+   * 
+   * @return the {@link Provider} of this instance.
    */
   public final Provider getProvider()
   {
@@ -243,9 +188,9 @@ public abstract class MessageDigest extends MessageDigestSpi
   }
 
   /**
-   * Updates the digest using the specified byte.
-   *
-   * @param input the byte with which to update the digest.
+   * Updates the digest with the byte.
+   * 
+   * @param input byte to update the digest with.
    */
   public void update(byte input)
   {
@@ -253,12 +198,15 @@ public abstract class MessageDigest extends MessageDigestSpi
   }
 
   /**
-   * Updates the digest using the specified array of bytes, starting at the
-   * specified offset.
-   *
-   * @param input the array of bytes.
-   * @param offset the offset to start from in the array of bytes.
-   * @param len the number of bytes to use, starting at offset.
+   * Updates the digest with the bytes from the array starting from the
+   * specified offset and using the specified length of bytes.
+   * 
+   * @param input
+   *          bytes to update the digest with.
+   * @param offset
+   *          the offset to start at.
+   * @param len
+   *          length of the data to update with.
    */
   public void update(byte[] input, int offset, int len)
   {
@@ -266,9 +214,9 @@ public abstract class MessageDigest extends MessageDigestSpi
   }
 
   /**
-   * Updates the digest using the specified array of bytes.
-   *
-   * @param input the array of bytes.
+   * Updates the digest with the bytes of an array.
+   * 
+   * @param input bytes to update the digest with.
    */
   public void update(byte[] input)
   {
@@ -276,10 +224,9 @@ public abstract class MessageDigest extends MessageDigestSpi
   }
 
   /**
-   * Completes the hash computation by performing final operations such as
-   * padding. The digest is reset after this call is made.
-   *
-   * @return the array of bytes for the resulting hash value.
+   * Computes the final digest of the stored data.
+   * 
+   * @return a byte array representing the message digest.
    */
   public byte[] digest()
   {
@@ -287,14 +234,15 @@ public abstract class MessageDigest extends MessageDigestSpi
   }
 
   /**
-   * Completes the hash computation by performing final operations such as
-   * padding. The digest is reset after this call is made.
-   *
-   * @param buf An output buffer for the computed digest.
-   * @param offset The offset into the output buffer to begin storing the digest.
-   * @param len The number of bytes within buf allotted for the digest.
-   * @return The number of bytes placed into buf.
-   * @throws DigestException if an error occurs.
+   * Computes the final digest of the stored bytes and returns the result.
+   * 
+   * @param buf
+   *          an array of bytes to store the result in.
+   * @param offset
+   *          an offset to start storing the result at.
+   * @param len
+   *          the length of the buffer.
+   * @return Returns the length of the buffer.
    */
   public int digest(byte[] buf, int offset, int len) throws DigestException
   {
@@ -302,13 +250,13 @@ public abstract class MessageDigest extends MessageDigestSpi
   }
 
   /**
-   * Performs a final update on the digest using the specified array of bytes,
-   * then completes the digest computation. That is, this method first calls
-   * <code>update(input)</code>, passing the input array to the <code>update()
-   * </code> method, then calls <code>digest()</code>.
-   *
-   * @param input the input to be updated before the digest is completed.
-   * @return the array of bytes for the resulting hash value.
+   * Computes a final update using the input array of bytes, then computes a
+   * final digest and returns it. It calls {@link #update(byte[])} and then
+   * {@link #digest(byte[])}.
+   * 
+   * @param input
+   *          an array of bytes to perform final update with.
+   * @return a byte array representing the message digest.
    */
   public byte[] digest(byte[] input)
   {
@@ -317,9 +265,9 @@ public abstract class MessageDigest extends MessageDigestSpi
   }
 
   /**
-   * Returns a string representation of this message digest object.
-   *
-   * @return a string representation of the object.
+   * Returns a string representation of this instance.
+   * 
+   * @return a string representation of this instance.
    */
   public String toString()
   {
@@ -327,12 +275,14 @@ public abstract class MessageDigest extends MessageDigestSpi
   }
 
   /**
-   * Compares two digests for equality. Does a simple byte compare.
-   *
-   * @param digesta one of the digests to compare.
-   * @param digestb the other digest to compare.
-   * @return <code>true</code> if the digests are equal, <code>false</code>
-   * otherwise.
+   * Does a simple byte comparison of the two digests.
+   * 
+   * @param digesta
+   *          first digest to compare.
+   * @param digestb
+   *          second digest to compare.
+   * @return <code>true</code> if both are equal, <code>false</code>
+   *         otherwise.
    */
   public static boolean isEqual(byte[] digesta, byte[] digestb)
   {
@@ -346,20 +296,16 @@ public abstract class MessageDigest extends MessageDigestSpi
     return true;
   }
 
-  /** Resets the digest for further use. */
+  /** Resets this instance. */
   public void reset()
   {
     engineReset();
   }
 
   /**
-   * Returns a string that identifies the algorithm, independent of
-   * implementation details. The name should be a standard Java Security name
-   * (such as <code>"SHA"</code>, <code>"MD5"</code>, and so on). See Appendix
-   * A in the Java Cryptography Architecture API Specification &amp; Reference
-   * for information about standard algorithm names.
-   *
-   * @return the name of the algorithm.
+   * Returns the name of message digest algorithm.
+   * 
+   * @return the name of message digest algorithm.
    */
   public final String getAlgorithm()
   {
@@ -367,12 +313,10 @@ public abstract class MessageDigest extends MessageDigestSpi
   }
 
   /**
-   * Returns the length of the digest in bytes, or <code>0</code> if this
-   * operation is not supported by the provider and the implementation is not
-   * cloneable.
-   *
-   * @return the digest length in bytes, or <code>0</code> if this operation is
-   * not supported by the provider and the implementation is not cloneable.
+   * Returns the length of the message digest. The default is zero which means
+   * that the concrete implementation does not implement this method.
+   * 
+   * @return length of the message digest.
    * @since 1.2
    */
   public final int getDigestLength()
@@ -381,11 +325,14 @@ public abstract class MessageDigest extends MessageDigestSpi
   }
 
   /**
-   * Returns a clone if the implementation is cloneable.
-   *
-   * @return a clone if the implementation is cloneable.
-   * @throws CloneNotSupportedException if this is called on an implementation
-   * that does not support {@link Cloneable}.
+   * Returns a clone of this instance if cloning is supported. If it does not
+   * then a {@link CloneNotSupportedException} is thrown. Cloning depends on
+   * whether the subclass {@link MessageDigestSpi} implements {@link Cloneable}
+   * which contains the actual implementation of the appropriate algorithm.
+   * 
+   * @return a clone of this instance.
+   * @throws CloneNotSupportedException
+   *           the implementation does not support cloning.
    */
   public Object clone() throws CloneNotSupportedException
   {
diff --git a/java/security/Policy.java b/java/security/Policy.java
index 03d9bbb4e..de1ab80ef 100644
--- a/java/security/Policy.java
+++ b/java/security/Policy.java
@@ -43,49 +43,43 @@ import java.util.LinkedHashMap;
 import java.util.Map;
 
 /**
- * <p>This is an abstract class for representing the system security policy for
- * a Java application environment (specifying which permissions are available
- * for code from various sources). That is, the security policy is represented
- * by a <code>Policy</code> subclass providing an implementation of the abstract
- * methods in this <code>Policy</code> class.</p>
- *
- * <p>There is only one <code>Policy</code> object in effect at any given time.
- * </p>
- *
- * <p>The source location for the policy information utilized by the
- * <code>Policy</code> object is up to the <code>Policy</code> implementation.
- * The policy configuration may be stored, for example, as a flat ASCII file, as
- * a serialized binary file of the <code>Policy</code> class, or as a database.
- * </p>
- *
- * <p>The currently-installed <code>Policy</code> object can be obtained by
- * calling the <code>getPolicy()</code> method, and it can be changed by a call
- * to the <code>setPolicy()</code> method (by code with permission to reset the
- * <code>Policy</code>).</p>
- *
- * <p>The <code>refresh()</code> method causes the policy object to refresh /
- * reload its current configuration.</p>
- *
- * <p>This is implementation-dependent. For example, if the policy object stores
- * its policy in configuration files, calling <code>refresh()</code> will cause
- * it to re-read the configuration policy files. The refreshed policy may not
- * have an effect on classes in a particular {@link ProtectionDomain}. This is
- * dependent on the <code>Policy</code> provider's implementation of the
- * <code>implies()</code> method and the {@link PermissionCollection} caching
- * strategy.</p>
- *
+ * <code>Policy</code> is an abstract class for managing the system security
+ * policy for the Java application environment. It specifies which permissions
+ * are available for code from various sources. The security policy is
+ * represented through a subclass of <code>Policy</code>.
+ * 
+ * <p>Only one <code>Policy</code> is in effect at any time. A
+ * {@link ProtectionDomain} initializes itself with information from this class
+ * on the set of permssions to grant.</p>
+ * 
+ * <p>The location for the actual <code>Policy</code> could be anywhere in any
+ * form because it depends on the Policy implementation. The default system is
+ * in a flat ASCII file or it could be in a database.</p>
+ * 
+ * <p>The current installed <code>Policy</code> can be accessed with
+ * {@link #getPolicy()} and changed with {@link #setPolicy(Policy)} if the code
+ * has the correct permissions.</p>
+ * 
+ * <p>The {@link #refresh()} method causes the <code>Policy</code> instance to
+ * refresh/reload its configuration. The method used to refresh depends on the
+ * <code>Policy</code> implementation.</p>
+ * 
+ * <p>When a protection domain initializes its permissions, it uses code like
+ * the following:</p>
+ * 
+ * <code>
+ * policy = Policy.getPolicy();
+ * PermissionCollection perms = policy.getPermissions(myCodeSource);
+ * </code>
+ * 
+ * <p>The protection domain passes the <code>Policy</code> handler a
+ * {@link CodeSource} instance which contains the codebase URL and a public key.
+ * The <code>Policy</code> implementation then returns the proper set of
+ * permissions for that {@link CodeSource}.</p>
+ * 
  * <p>The default <code>Policy</code> implementation can be changed by setting
- * the value of the <code>"policy.provider"</code> security property (in the
- * Java security properties file) to the fully qualified name of the desired
- * <code>Policy</code> implementation class. The Java security properties file
- * is located in the file named <code>&lt;JAVA_HOME>/lib/security/java.security
- * </code>, where <code>&lt;JAVA_HOME></code> refers to the directory where the
- * SDK was installed.</p>
- *
- * <p><b>IMPLEMENTATION NOTE:</b> This implementation attempts to read the
- * System property named <code>policy.provider</code> to find the concrete
- * implementation of the <code>Policy</code>. If/when this fails, it falls back
- * to a default implementation, which <b>allows everything</b>.
+ * the "policy.provider" security provider in the "java.security" file to the
+ * correct <code>Policy</code> implementation class.</p>
  *
  * @author Mark Benvenuto
  * @see CodeSource
@@ -106,18 +100,14 @@ public abstract class Policy
   }
 
   /**
-   * Returns the installed <code>Policy</code> object. This value should not be
-   * cached, as it may be changed by a call to <code>setPolicy()</code>. This
-   * method first calls {@link SecurityManager#checkPermission(Permission)} with
-   * a <code>SecurityPermission("getPolicy")</code> permission to ensure it's ok
-   * to get the <code>Policy</code> object.
-   *
-   * @return the installed <code>Policy</code>.
-   * @throws SecurityException if a security manager exists and its
-   * <code>checkPermission()</code> method doesn't allow getting the
-   * <code>Policy</code> object.
-   * @see SecurityManager#checkPermission(Permission)
-   * @see #setPolicy(Policy)
+   * Returns the currently installed <code>Policy</code> handler. The value
+   * should not be cached as it can be changed any time by
+   * {@link #setPolicy(Policy)}.
+   * 
+   * @return the current <code>Policy</code>.
+   * @throws SecurityException
+   *           if a {@link SecurityManager} is installed which disallows this
+   *           operation.
    */
   public static Policy getPolicy()
   {
@@ -129,17 +119,13 @@ public abstract class Policy
   }
 
   /**
-   * Sets the system-wide <code>Policy</code> object. This method first calls
-   * {@link SecurityManager#checkPermission(Permission)} with a
-   * <code>SecurityPermission("setPolicy")</code> permission to ensure it's ok
-   * to set the <code>Policy</code>.
-   *
-   * @param policy the new system <code>Policy</code> object.
-   * @throws SecurityException if a security manager exists and its
-   * <code>checkPermission()</code> method doesn't allow setting the
-   * <code>Policy</code>.
-   * @see SecurityManager#checkPermission(Permission)
-   * @see #getPolicy()
+   * Sets the <code>Policy</code> handler to a new value.
+   * 
+   * @param policy
+   *          the new <code>Policy</code> to use.
+   * @throws SecurityException
+   *           if a {@link SecurityManager} is installed which disallows this
+   *           operation.
    */
   public static void setPolicy(Policy policy)
   {
@@ -213,28 +199,27 @@ public abstract class Policy
   }
 
   /**
-   * Evaluates the global policy and returns a {@link PermissionCollection}
-   * object specifying the set of permissions allowed for code from the
-   * specified code source.
-   *
-   * @param codesource the {@link CodeSource} associated with the caller. This
-   * encapsulates the original location of the code (where the code came from)
-   * and the public key(s) of its signer.
-   * @return the set of permissions allowed for code from codesource according
-   * to the policy. The returned set of permissions must be a new mutable
-   * instance and it must support heterogeneous {@link Permission} types.
+   * Returns the set of Permissions allowed for a given {@link CodeSource}.
+   * 
+   * @param codesource
+   *          the {@link CodeSource} for which, the caller needs to find the
+   *          set of granted permissions.
+   * @return a set of permissions for {@link CodeSource} specified by the
+   *         current <code>Policy</code>.
+   * @throws SecurityException
+   *           if a {@link SecurityManager} is installed which disallows this
+   *           operation.
    */
   public abstract PermissionCollection getPermissions(CodeSource codesource);
 
   /**
-   * Evaluates the global policy and returns a {@link PermissionCollection}
-   * object specifying the set of permissions allowed given the characteristics
-   * of the protection domain.
-   *
-   * @param domain the {@link ProtectionDomain} associated with the caller.
-   * @return the set of permissions allowed for the domain according to the
-   * policy. The returned set of permissions must be a new mutable instance and
-   * it must support heterogeneous {@link Permission} types.
+   * Returns the set of Permissions allowed for a given {@link ProtectionDomain}.
+   * 
+   * @param domain
+   *          the {@link ProtectionDomain} for which, the caller needs to find
+   *          the set of granted permissions.
+   * @return a set of permissions for {@link ProtectionDomain} specified by the
+   *         current <code>Policy.</code>.
    * @since 1.4
    * @see ProtectionDomain
    * @see SecureClassLoader
@@ -270,14 +255,16 @@ public abstract class Policy
   }
 
   /**
-   * Evaluates the global policy for the permissions granted to the {@link
-   * ProtectionDomain} and tests whether the <code>permission</code> is granted.
-   *
-   * @param domain the {@link ProtectionDomain} to test.
-   * @param permission the {@link Permission} object to be tested for
-   * implication.
-   * @return <code>true</code> if <code>permission</code> is a proper subset of
-   * a permission granted to this {@link ProtectionDomain}.
+   * Checks if the designated {@link Permission} is granted to a designated
+   * {@link ProtectionDomain}.
+   * 
+   * @param domain
+   *          the {@link ProtectionDomain} to test.
+   * @param permission
+   *          the {@link Permission} to check.
+   * @return <code>true</code> if <code>permission</code> is implied by a
+   *         permission granted to this {@link ProtectionDomain}. Returns
+   *         <code>false</code> otherwise.
    * @since 1.4
    * @see ProtectionDomain
    */
@@ -302,9 +289,9 @@ public abstract class Policy
   }
 
   /**
-   * Refreshes/reloads the policy configuration. The behavior of this method
-   * depends on the implementation. For example, calling refresh on a file-based
-   * policy will cause the file to be re-read.
+   * Causes this <code>Policy</code> instance to refresh / reload its
+   * configuration. The method used to refresh depends on the concrete
+   * implementation.
    */
   public abstract void refresh();
 }
diff --git a/java/security/ProtectionDomain.java b/java/security/ProtectionDomain.java
index a8a093925..33af8fdb8 100644
--- a/java/security/ProtectionDomain.java
+++ b/java/security/ProtectionDomain.java
@@ -40,17 +40,14 @@ package java.security;
 import gnu.classpath.SystemProperties;
 
 /**
- * <p>This <code>ProtectionDomain</code> class encapsulates the characteristics
- * of a domain, which encloses a set of classes whose instances are granted a
- * set of permissions when being executed on behalf of a given set of
- * <i>Principals</i>.
- *
- * <p>A static set of permissions can be bound to a <code>ProtectionDomain</code>
- * when it is constructed; such permissions are granted to the domain regardless
- * of the {@link Policy} in force. However, to support dynamic security
- * policies, a <code>ProtectionDomain</code> can also be constructed such that
- * it is dynamically mapped to a set of permissions by the current {@link
- * Policy} whenever a permission is checked.</p>
+ * This class represents a group of classes, along with their granted
+ * permissions. The classes are identified by a {@link CodeSource}. Thus, any
+ * class loaded from the specified {@link CodeSource} is treated as part of
+ * this domain. The set of permissions is represented by an instance of
+ * {@link PermissionCollection}.
+ * 
+ * <p>Every class in the system will belong to one and only one
+ * <code>ProtectionDomain</code>.</p>
  *
  * @author Aaron M. Renn (arenn@urbanophile.com)
  * @version 0.0
@@ -73,15 +70,17 @@ public class ProtectionDomain
   private boolean staticBinding;
 
   /**
-   * Creates a new <code>ProtectionDomain</code> with the given {@link
-   * CodeSource} and {@link Permissions}. If the permissions object is not
-   * <code>null</code>, then <code>setReadOnly()</code> will be called on the
-   * passed in {@link Permissions} object. The only permissions granted to this
-   * domain are the ones specified; the current {@link Policy} will not be
-   * consulted.
-   *
-   * @param codesource the codesource associated with this domain.
-   * @param permissions the permissions granted to this domain
+   * Initializes a new instance of <code>ProtectionDomain</code> representing
+   * the specified {@link CodeSource} and set of permissions. No permissions
+   * can be added later to the {@link PermissionCollection} and this contructor
+   * will call the <code>setReadOnly</code> method on the specified set of
+   * permissions.
+   * 
+   * @param codesource
+   *          The {@link CodeSource} for this domain.
+   * @param permissions
+   *          The set of permissions for this domain.
+   * @see PermissionCollection#setReadOnly()
    */
   public ProtectionDomain(CodeSource codesource, PermissionCollection permissions)
   {
@@ -89,28 +88,25 @@ public class ProtectionDomain
   }
 
   /**
-   * <p>Creates a new ProtectionDomain qualified by the given CodeSource,
-   * Permissions, ClassLoader and array of Principals. If the permissions
-   * object is not null, then <code>setReadOnly()</code> will be called on the
-   * passed in Permissions object. The permissions granted to this domain are
-   * dynamic; they include both the static permissions passed to this
-   * constructor, and any permissions granted to this domain by the current
-   * Policy at the time a permission is checked.</p>
-   *
-   * <p>This constructor is typically used by {@link ClassLoader}s and {@link
-   * DomainCombiner}s which delegate to <code>Policy</code> to actively
-   * associate the permissions granted to this domain. This constructor affords
-   * the Policy provider the opportunity to augment the supplied
-   * PermissionCollection to reflect policy changes.</p>
-   *
-   * @param codesource the CodeSource associated with this domain.
-   * @param permissions the permissions granted to this domain.
-   * @param classloader the ClassLoader associated with this domain.
-   * @param principals the array of Principals associated with this domain.
+   * This method initializes a new instance of <code>ProtectionDomain</code>
+   * given its {@link CodeSource}, granted permissions, associated
+   * {@link ClassLoader} and {@link Principal}s.
+   * 
+   * <p>Similar to the previous constructor, if the designated set of
+   * permissions is not <code>null</code>, the <code>setReadOnly</code> method
+   * is called on that set.</p>
+   * 
+   * @param codesource
+   *          The {@link CodeSource} for this domain.
+   * @param permissions
+   *          The permission set for this domain.
+   * @param classloader
+   *          the ClassLoader associated with this domain.
+   * @param principals
+   *          the array of {@link Principal}s associated with this domain.
    * @since 1.4
-   * @see Policy#refresh()
-   * @see Policy#getPermissions(ProtectionDomain)
-  */
+   * @see PermissionCollection#setReadOnly()
+   */
   public ProtectionDomain(CodeSource codesource,
                           PermissionCollection permissions,
                           ClassLoader classloader, Principal[] principals)
@@ -140,8 +136,8 @@ public class ProtectionDomain
 
   /**
    * Returns the {@link CodeSource} of this domain.
-   *
-   * @return the {@link CodeSource} of this domain which may be <code>null</code>.
+   * 
+   * @return the {@link CodeSource} of this domain.
    * @since 1.2
    */
   public final CodeSource getCodeSource()
@@ -151,9 +147,8 @@ public class ProtectionDomain
 
   /**
    * Returns the {@link ClassLoader} of this domain.
-   *
-   * @return the {@link ClassLoader} of this domain which may be
-   * <code>null</code>.
+   * 
+   * @return the {@link ClassLoader} of this domain.
    * @since 1.4
    */
   public final ClassLoader getClassLoader()
@@ -162,10 +157,9 @@ public class ProtectionDomain
   }
 
   /**
-   * Returns an array of principals for this domain.
-   *
-   * @return returns a non-null array of principals for this domain. Changes to
-   * this array will have no impact on the <code>ProtectionDomain</code>.
+   * Returns a clone of the {@link Principal}s of this domain.
+   * 
+   * @return a clone of the {@link Principal}s of this domain.
    * @since 1.4
    */
   public final Principal[] getPrincipals()
@@ -174,12 +168,9 @@ public class ProtectionDomain
   }
 
   /**
-   * Returns the static permissions granted to this domain.
-   *
-   * @return the static set of permissions for this domain which may be
-   * <code>null</code>.
-   * @see Policy#refresh()
-   * @see Policy#getPermissions(ProtectionDomain)
+   * Returns the {@link PermissionCollection} of this domain.
+   * 
+   * @return The {@link PermissionCollection} of this domain.
    */
   public final PermissionCollection getPermissions()
   {
@@ -187,26 +178,13 @@ public class ProtectionDomain
   }
 
   /**
-   * <p>Check and see if this <code>ProtectionDomain</code> implies the
-   * permissions expressed in the <code>Permission</code> object.</p>
-   *
-   * <p>The set of permissions evaluated is a function of whether the
-   * <code>ProtectionDomain</code> was constructed with a static set of
-   * permissions or it was bound to a dynamically mapped set of permissions.</p>
-   *
-   * <p>If the <code>ProtectionDomain</code> was constructed to a statically
-   * bound {@link PermissionCollection} then the permission will only be checked
-   * against the {@link PermissionCollection} supplied at construction.</p>
-   *
-   * <p>However, if the <code>ProtectionDomain</code> was constructed with the
-   * constructor variant which supports dynamically binding permissions, then
-   * the permission will be checked against the combination of the
-   * {@link PermissionCollection} supplied at construction and the current
-   * {@link Policy} binding.
-   *
-   * @param permission the {@link Permission} object to check.
-   * @return <code>true</code> if <code>permission</code> is implicit to this
-   * <code>ProtectionDomain</code>.
+   * Tests whether or not the specified {@link Permission} is implied by the
+   * set of permissions granted to this domain.
+   * 
+   * @param permission
+   *          the {@link Permission} to test.
+   * @return <code>true</code> if the specified {@link Permission} is implied
+   *         for this domain, <code>false</code> otherwise.
    */
   public boolean implies(Permission permission)
   {
@@ -218,9 +196,10 @@ public class ProtectionDomain
   }
 
   /**
-   * Convert a <code>ProtectionDomain</code> to a String.
-   *
-   * @return a string representation of the object.
+   * Returns a string representation of this object. It will include the
+   * {@link CodeSource} and set of permissions associated with this domain.
+   * 
+   * @return A string representation of this object.
    */
   public String toString()
   {
diff --git a/java/security/Security.java b/java/security/Security.java
index d26d049c5..3aabed850 100644
--- a/java/security/Security.java
+++ b/java/security/Security.java
@@ -60,7 +60,7 @@ import java.util.Vector;
 
 /**
  * This class centralizes all security properties and common security methods.
- * One of its primary uses is to manage providers.
+ * One of its primary uses is to manage security providers.
  *
  * @author Mark Benvenuto (ivymccough@worldnet.att.net)
  */
@@ -110,9 +110,9 @@ public final class Security
   }
 
   /**
-   * Tries to load the vender specific security providers from the given
-   * base URL. Returns true if the resource could be read and completely
-   * parsed successfully, false otherwise.
+   * Tries to load the vender specific security providers from the given base
+   * URL. Returns true if the resource could be read and completely parsed
+   * successfully, false otherwise.
    */
   private static boolean loadProviders(String baseUrl, String vendor)
   {
@@ -166,22 +166,18 @@ public final class Security
   }
 
   /**
-   * Gets a specified property for an algorithm. The algorithm name should be a
-   * standard name. See Appendix A in the Java Cryptography Architecture API
-   * Specification &amp; Reference for information about standard algorithm
-   * names. One possible use is by specialized algorithm parsers, which may map
-   * classes to algorithms which they understand (much like {@link Key} parsers
-   * do).
-   *
-   * @param algName the algorithm name.
-   * @param propName the name of the property to get.
-   * @return the value of the specified property.
-   * @deprecated This method used to return the value of a proprietary property
-   * in the master file of the "SUN" Cryptographic Service Provider in order to
-   * determine how to parse algorithm-specific parameters. Use the new
-   * provider-based and algorithm-independent {@link AlgorithmParameters} and
-   * {@link KeyFactory} engine classes (introduced in the Java 2 platform)
-   * instead.
+   * Returns the value associated to a designated property name for a given
+   * algorithm.
+   * 
+   * @param algName
+   *          the algorithm name.
+   * @param propName
+   *          the name of the property to return.
+   * @return the value of the specified property or <code>null</code> if none
+   *         found.
+   * @deprecated Use the provider-based and algorithm-independent
+   *             {@link AlgorithmParameters} and {@link KeyFactory} engine
+   *             classes instead.
    */
   public static String getAlgorithmProperty(String algName, String propName)
   {
@@ -204,37 +200,21 @@ public final class Security
   }
 
   /**
-   * <p>Adds a new provider, at a specified position. The position is the
-   * preference order in which providers are searched for requested algorithms.
-   * Note that it is not guaranteed that this preference will be respected. The
-   * position is 1-based, that is, <code>1</code> is most preferred, followed by
-   * <code>2</code>, and so on.</p>
-   *
-   * <p>If the given provider is installed at the requested position, the
-   * provider that used to be at that position, and all providers with a
-   * position greater than position, are shifted up one position (towards the
-   * end of the list of installed providers).</p>
-   *
-   * <p>A provider cannot be added if it is already installed.</p>
-   *
-   * <p>First, if there is a security manager, its <code>checkSecurityAccess()
-   * </code> method is called with the string <code>"insertProvider."+provider.
-   * getName()</code> to see if it's ok to add a new provider. If the default
-   * implementation of <code>checkSecurityAccess()</code> is used (i.e., that
-   * method is not overriden), then this will result in a call to the security
-   * manager's <code>checkPermission()</code> method with a
-   * <code>SecurityPermission("insertProvider."+provider.getName())</code>
-   * permission.</p>
-   *
-   * @param provider the provider to be added.
-   * @param position the preference position that the caller would like for
-   * this provider.
-   * @return the actual preference position in which the provider was added, or
-   * <code>-1</code> if the provider was not added because it is already
-   * installed.
-   * @throws SecurityException if a security manager exists and its
-   * {@link SecurityManager#checkSecurityAccess(String)} method denies access
-   * to add a new provider.
+   * Inserts a new designated {@link Provider} at a designated (1-based)
+   * position in the current list of installed {@link Provider}s,
+   * 
+   * @param provider
+   *          the new {@link Provider} to add.
+   * @param position
+   *          the position (starting from 1) of where to install
+   *          <code>provider</code>.
+   * @return the actual position, in the list of installed Providers. Returns
+   *         <code>-1</code> if <code>provider</code> was laready in the
+   *         list. The actual position may be different than the desired
+   *         <code>position</code>.
+   * @throws SecurityException
+   *           if a {@link SecurityManager} is installed and it disallows this
+   *           operation.
    * @see #getProvider(String)
    * @see #removeProvider(String)
    * @see SecurityPermission
@@ -264,24 +244,17 @@ public final class Security
   }
 
   /**
-   * <p>Adds a provider to the next position available.</p>
-   *
-   * <p>First, if there is a security manager, its <code>checkSecurityAccess()
-   * </code> method is called with the string <code>"insertProvider."+provider.
-   * getName()</code> to see if it's ok to add a new provider. If the default
-   * implementation of <code>checkSecurityAccess()</code> is used (i.e., that
-   * method is not overriden), then this will result in a call to the security
-   * manager's <code>checkPermission()</code> method with a
-   * <code>SecurityPermission("insertProvider."+provider.getName())</code>
-   * permission.</p>
-   *
-   * @param provider the provider to be added.
-   * @return the preference position in which the provider was added, or
-   * <code>-1</code> if the provider was not added because it is already
-   * installed.
-   * @throws SecurityException if a security manager exists and its
-   * {@link SecurityManager#checkSecurityAccess(String)} method denies access
-   * to add a new provider.
+   * Appends the designated new {@link Provider} to the current list of
+   * installed {@link Provider}s.
+   * 
+   * @param provider
+   *          the new {@link Provider} to append.
+   * @return the position (starting from 1) of <code>provider</code> in the
+   *         current list of {@link Provider}s, or <code>-1</code> if
+   *         <code>provider</code> was already there.
+   * @throws SecurityException
+   *           if a {@link SecurityManager} is installed and it disallows this
+   *           operation.
    * @see #getProvider(String)
    * @see #removeProvider(String)
    * @see SecurityPermission
@@ -292,26 +265,14 @@ public final class Security
   }
 
   /**
-   * <p>Removes the provider with the specified name.</p>
-   *
-   * <p>When the specified provider is removed, all providers located at a
-   * position greater than where the specified provider was are shifted down
-   * one position (towards the head of the list of installed providers).</p>
-   *
-   * <p>This method returns silently if the provider is not installed.</p>
-   *
-   * <p>First, if there is a security manager, its <code>checkSecurityAccess()
-   * </code> method is called with the string <code>"removeProvider."+name</code>
-   * to see if it's ok to remove the provider. If the default implementation of
-   * <code>checkSecurityAccess()</code> is used (i.e., that method is not
-   * overriden), then this will result in a call to the security manager's
-   * <code>checkPermission()</code> method with a <code>SecurityPermission(
-   * "removeProvider."+name)</code> permission.</p>
-   *
-   * @param name the name of the provider to remove.
-   * @throws SecurityException if a security manager exists and its
-   * {@link SecurityManager#checkSecurityAccess(String)} method denies access
-   * to remove the provider.
+   * Removes an already installed {@link Provider}, given its name, from the
+   * current list of installed {@link Provider}s.
+   * 
+   * @param name
+   *          the name of an already installed {@link Provider} to remove.
+   * @throws SecurityException
+   *           if a {@link SecurityManager} is installed and it disallows this
+   *           operation.
    * @see #getProvider(String)
    * @see #addProvider(Provider)
    */
@@ -333,9 +294,9 @@ public final class Security
   }
 
   /**
-   * Returns an array containing all the installed providers. The order of the
-   * providers in the array is their preference order.
-   *
+   * Returns the current list of installed {@link Provider}s as an array
+   * ordered according to their installation preference order.
+   * 
    * @return an array of all the installed providers.
    */
   public static Provider[] getProviders()
@@ -346,11 +307,13 @@ public final class Security
   }
 
   /**
-   * Returns the provider installed with the specified name, if any. Returns
-   * <code>null</code> if no provider with the specified name is installed.
-   *
-   * @param name the name of the provider to get.
-   * @return the provider of the specified name.
+   * Returns an already installed {@link Provider} given its name.
+   * 
+   * @param name
+   *          the name of an already installed {@link Provider}.
+   * @return the {@link Provider} known by <code>name</code>. Returns
+   *         <code>null</code> if the current list of {@link Provider}s does
+   *         not include one named <code>name</code>.
    * @see #removeProvider(String)
    * @see #addProvider(Provider)
    */
@@ -376,18 +339,16 @@ public final class Security
   }
 
   /**
-   * <p>Gets a security property value.</p>
-   *
-   * <p>First, if there is a security manager, its <code>checkPermission()</code>
-   * method is called with a <code>SecurityPermission("getProperty."+key)</code>
-   * permission to see if it's ok to retrieve the specified security property
-   * value.</p>
-   *
-   * @param key the key of the property being retrieved.
-   * @return the value of the security property corresponding to key.
-   * @throws SecurityException if a security manager exists and its
-   * {@link SecurityManager#checkPermission(Permission)} method denies access
-   * to retrieve the specified security property value.
+   * Returns the value associated with a Security propery.
+   * 
+   * @param key
+   *          the key of the property to fetch.
+   * @return the value of the Security property associated with
+   *         <code>key</code>. Returns <code>null</code> if no such property
+   *         was found.
+   * @throws SecurityException
+   *           if a {@link SecurityManager} is installed and it disallows this
+   *           operation.
    * @see #setProperty(String, String)
    * @see SecurityPermission
    */
@@ -404,18 +365,15 @@ public final class Security
   }
 
   /**
-   * <p>Sets a security property value.</p>
-   *
-   * <p>First, if there is a security manager, its <code>checkPermission()</code>
-   * method is called with a <code>SecurityPermission("setProperty."+key)</code>
-   * permission to see if it's ok to set the specified security property value.
-   * </p>
-   *
-   * @param key the name of the property to be set.
-   * @param datum the value of the property to be set.
-   * @throws SecurityException if a security manager exists and its
-   * {@link SecurityManager#checkPermission(Permission)} method denies access
-   * to set the specified security property value.
+   * Sets or changes a designated Security property to a designated value.
+   * 
+   * @param key
+   *          the name of the property to set.
+   * @param datum
+   *          the new value of the property.
+   * @throws SecurityException
+   *           if a {@link SecurityManager} is installed and it disallows this
+   *           operation.
    * @see #getProperty(String)
    * @see SecurityPermission
    */
@@ -432,19 +390,16 @@ public final class Security
   }
 
   /**
-   * Returns a Set of Strings containing the names of all available algorithms
-   * or types for the specified Java cryptographic service (e.g., Signature,
-   * MessageDigest, Cipher, Mac, KeyStore). Returns an empty Set if there is no
-   * provider that supports the specified service. For a complete list of Java
-   * cryptographic services, please see the Java Cryptography Architecture API
-   * Specification &amp; Reference. Note: the returned set is immutable.
-   *
-   * @param serviceName the name of the Java cryptographic service (e.g.,
-   * Signature, MessageDigest, Cipher, Mac, KeyStore). Note: this parameter is
-   * case-insensitive.
-   * @return a Set of Strings containing the names of all available algorithms
-   * or types for the specified Java cryptographic service or an empty set if
-   * no provider supports the specified service.
+   * For a given <i>service</i> (e.g. Signature, MessageDigest, etc...) this
+   * method returns the {@link Set} of all available algorithm names (instances
+   * of {@link String}, from all currently installed {@link Provider}s.
+   * 
+   * @param serviceName
+   *          the case-insensitive name of a service (e.g. Signature,
+   *          MessageDigest, etc).
+   * @return a {@link Set} of {@link String}s containing the names of all
+   *         algorithm names provided by all of the currently installed
+   *         {@link Provider}s.
    * @since 1.4
    */
   public static Set getAlgorithms(String serviceName)
@@ -477,53 +432,48 @@ public final class Security
   }
 
   /**
-   * <p>Returns an array containing all installed providers that satisfy the
-   * specified selection criterion, or <code>null</code> if no such providers
-   * have been installed. The returned providers are ordered according to their
-   * preference order.</p>
-   *
-   * <p>A cryptographic service is always associated with a particular
-   * algorithm or type. For example, a digital signature service is always
-   * associated with a particular algorithm (e.g., <i>DSA</i>), and a
-   * CertificateFactory service is always associated with a particular
-   * certificate type (e.g., <i>X.509</i>).</p>
-   *
-   * <p>The selection criterion must be specified in one of the following two
-   * formats:</p>
-   *
+   * Returns an array of currently installed {@link Provider}s, ordered
+   * according to their installation preference order, which satisfy a given
+   * <i>selection</i> criterion.
+   * 
+   * <p>This implementation recognizes a <i>selection</i> criterion written in
+   * one of two following forms:</p>
+   * 
    * <ul>
-   *    <li><p>&lt;crypto_service&gt;.&lt;algorithm_or_type&gt;</p>
-   *    <p>The cryptographic service name must not contain any dots.</p>
-   *    <p>A provider satisfies the specified selection criterion iff the
-   *    provider implements the specified algorithm or type for the specified
-   *    cryptographic service.</p>
-   *    <p>For example, "CertificateFactory.X.509" would be satisfied by any
-   *    provider that supplied a CertificateFactory implementation for X.509
-   *    certificates.</p></li>
-   *
-   *    <li><p>&lt;crypto_service&gt;.&lt;algorithm_or_type&gt; &lt;attribute_name&gt;:&lt;attribute_value&gt;</p>
-   *    <p>The cryptographic service name must not contain any dots. There must
-   *    be one or more space charaters between the the &lt;algorithm_or_type&gt;
-   *    and the &lt;attribute_name&gt;.</p>
-   *    <p>A provider satisfies this selection criterion iff the provider
-   *    implements the specified algorithm or type for the specified
-   *    cryptographic service and its implementation meets the constraint
-   *    expressed by the specified attribute name/value pair.</p>
-   *    <p>For example, "Signature.SHA1withDSA KeySize:1024" would be satisfied
-   *    by any provider that implemented the SHA1withDSA signature algorithm
-   *    with a keysize of 1024 (or larger).</p></li>
+   *   <li>&lt;crypto_service&gt;.&lt;algorithm_or_type&gt;: Where
+   *   <i>crypto_service</i> is a case-insensitive string, similar to what has
+   *   been described in the {@link #getAlgorithms(String)} method, and
+   *   <i>algorithm_or_type</i> is a known case-insensitive name of an
+   *   Algorithm, or one of its aliases.
+   *   
+   *   <p>For example, "CertificateFactory.X.509" would return all the installed
+   *   {@link Provider}s which provide a <i>CertificateFactory</i>
+   *   implementation of <i>X.509</i>.</p></li>
+   *   
+   *   <li>&lt;crypto_service&gt;.&lt;algorithm_or_type&gt; &lt;attribute_name&gt;:&lt;value&gt;:
+   *   Where <i>crypto_service</i> is a case-insensitive string, similar to what
+   *   has been described in the {@link #getAlgorithms(String)} method,
+   *   <i>algorithm_or_type</i> is a case-insensitive known name of an Algorithm
+   *   or one of its aliases, <i>attribute_name</i> is a case-insensitive
+   *   property name with no whitespace characters, and no dots, in-between, and
+   *   <i>value</i> is a {@link String} with no whitespace characters in-between.
+   *   
+   *   <p>For example, "Signature.Sha1WithDSS KeySize:1024" would return all the
+   *   installed {@link Provider}s which declared their ability to provide
+   *   <i>Signature</i> services, using the <i>Sha1WithDSS</i> algorithm with
+   *   key sizes of <i>1024</i>.</p></li>
    * </ul>
-   *
-   * <p>See Appendix A in the Java Cryptogaphy Architecture API Specification
-   * &amp; Reference for information about standard cryptographic service names,
-   * standard algorithm names and standard attribute names.</p>
-   *
-   * @param filter the criterion for selecting providers. The filter is case-
-   * insensitive.
-   * @return all the installed providers that satisfy the selection criterion,
-   * or null if no such providers have been installed.
-   * @throws InvalidParameterException if the filter is not in the required
-   * format.
+   * 
+   * @param filter
+   *          the <i>selection</i> criterion for selecting among the installed
+   *          {@link Provider}s.
+   * @return all the installed {@link Provider}s which satisfy the <i>selection</i>
+   *         criterion. Returns <code>null</code> if no installed
+   *         {@link Provider}s were found which satisfy the <i>selection</i>
+   *         criterion. Returns ALL installed {@link Provider}s if
+   *         <code>filter</code> is <code>null</code> or is an empty string.
+   * @throws InvalidParameterException
+   *           if an exception occurs while parsing the <code>filter</code>.
    * @see #getProviders(Map)
    */
   public static Provider[] getProviders(String filter)
@@ -544,48 +494,47 @@ public final class Security
     return getProviders(map);
   }
 
- /**
-  * <p>Returns an array containing all installed providers that satisfy the
-  * specified selection criteria, or <code>null</code> if no such providers
-  * have been installed. The returned providers are ordered according to their
-  * preference order.</p>
-  *
-  * <p>The selection criteria are represented by a map. Each map entry
-  * represents a selection criterion. A provider is selected iff it satisfies
-  * all selection criteria. The key for any entry in such a map must be in one
-  * of the following two formats:</p>
-  *
-  * <ul>
-  *    <li><p>&lt;crypto_service&gt;.&lt;algorithm_or_type&gt;</p>
-  *    <p>The cryptographic service name must not contain any dots.</p>
-  *    <p>The value associated with the key must be an empty string.</p>
-  *    <p>A provider satisfies this selection criterion iff the provider
-  *    implements the specified algorithm or type for the specified
-  *    cryptographic service.</p></li>
-  *
-  *    <li><p>&lt;crypto_service&gt;.&lt;algorithm_or_type&gt; &lt;attribute_name&gt;</p>
-  *    <p>The cryptographic service name must not contain any dots. There must
-  *    be one or more space charaters between the &lt;algorithm_or_type&gt; and
-  *    the &lt;attribute_name&gt;.</p>
-  *    <p>The value associated with the key must be a non-empty string. A
-  *    provider satisfies this selection criterion iff the provider implements
-  *    the specified algorithm or type for the specified cryptographic service
-  *    and its implementation meets the constraint expressed by the specified
-  *    attribute name/value pair.</p></li>
-  * </ul>
-  *
-  * <p>See Appendix A in the Java Cryptogaphy Architecture API Specification
-  * &amp; Reference for information about standard cryptographic service names,
-  * standard algorithm names and standard attribute names.</p>
-  *
-  * @param filter the criteria for selecting providers. The filter is case-
-  * insensitive.
-  * @return all the installed providers that satisfy the selection criteria,
-  * or <code>null</code> if no such providers have been installed.
-  * @throws InvalidParameterException if the filter is not in the required
-  * format.
-  * @see #getProviders(String)
-  */
+  /**
+   * Returns an array of currently installed {@link Provider}s which satisfy a
+   * set of <i>selection</i> criteria.
+   * 
+   * <p>The <i>selection</i> criteria are defined in a {@link Map} where each
+   * element specifies a <i>selection</i> querry. The <i>Keys</i> in this
+   * {@link Map} must be in one of the two following forms:</p>
+   * 
+   * <ul>
+   *   <li>&lt;crypto_service&gt;.&lt;algorithm_or_type&gt;: Where
+   *   <i>crypto_service</i> is a case-insensitive string, similar to what has
+   *   been described in the {@link #getAlgorithms(String)} method, and
+   *   <i>algorithm_or_type</i> is a case-insensitive known name of an
+   *   Algorithm, or one of its aliases. The <i>value</i> of the entry in the
+   *   {@link Map} for such a <i>Key</i> MUST be the empty string.
+   *   {@link Provider}s which provide an implementation for the designated
+   *   <i>service algorithm</i> are included in the result.</li>
+   *   
+   *   <li>&lt;crypto_service&gt;.&lt;algorithm_or_type&gt; &lt;attribute_name&gt;:
+   *   Where <i>crypto_service</i> is a case-insensitive string, similar to what
+   *   has been described in the {@link #getAlgorithms(String)} method,
+   *   <i>algorithm_or_type</i> is a case-insensitive known name of an Algorithm
+   *   or one of its aliases, and <i>attribute_name</i> is a case-insensitive
+   *   property name with no whitespace characters, and no dots, in-between. The
+   *   <i>value</i> of the entry in this {@link Map} for such a <i>Key</i> MUST
+   *   NOT be <code>null</code> or an empty string. {@link Provider}s which
+   *   declare the designated <i>attribute_name</i> and <i>value</i> for the
+   *   designated <i>service algorithm</i> are included in the result.</li>
+   * </ul>
+   * 
+   * @param filter
+   *          a {@link Map} of <i>selection querries</i>.
+   * @return all currently installed {@link Provider}s which satisfy ALL the
+   *         <i>selection</i> criteria defined in <code>filter</code>.
+   *         Returns ALL installed {@link Provider}s if <code>filter</code>
+   *         is <code>null</code> or empty.
+   * @throws InvalidParameterException
+   *           if an exception is encountered while parsing the syntax of the
+   *           {@link Map}'s <i>keys</i>.
+   * @see #getProviders(String)
+   */
   public static Provider[] getProviders(Map filter)
   {
     if (providers == null || providers.isEmpty())
diff --git a/java/security/Signature.java b/java/security/Signature.java
index 852c95922..845a77a8b 100644
--- a/java/security/Signature.java
+++ b/java/security/Signature.java
@@ -45,66 +45,36 @@ import java.security.cert.X509Certificate;
 import java.security.spec.AlgorithmParameterSpec;
 
 /**
- * <p>This <code>Signature</code> class is used to provide applications the
- * functionality of a digital signature algorithm. Digital signatures are used
- * for authentication and integrity assurance of digital data.</p>
- *
- * <p>The signature algorithm can be, among others, the NIST standard <i>DSS</i>,
- * using <i>DSA</i> and <i>SHA-1</i>. The <i>DSA</i> algorithm using the
- * <i>SHA-1</i> message digest algorithm can be specified as <code>SHA1withDSA
- * </code>. In the case of <i>RSA</i>, there are multiple choices for the
- * message digest algorithm, so the signing algorithm could be specified as, for
- * example, <code>MD2withRSA</code>, <code>MD5withRSA</code>, or
- * <code>SHA1withRSA</code>. The algorithm name must be specified, as there is
- * no default.</p>
- *
- * <p>Like other algorithm-based classes in Java Security, <code>Signature</code>
- * provides implementation-independent algorithms, whereby a caller (application
- * code) requests a particular signature algorithm and is handed back a properly
- * initialized <code>Signature</code> object. It is also possible, if desired,
- * to request a particular algorithm from a particular provider. See the
- * <code>getInstance()</code> methods.</p>
- *
- * <p>Thus, there are two ways to request a <code>Signature</code> algorithm
- * object: by specifying either just an algorithm name, or both an algorithm
- * name and a package provider.</p>
- *
- * <p>If just an algorithm name is specified, the system will determine if there
- * is an implementation of the algorithm requested available in the environment,
- * and if there is more than one, if there is a preferred one.</p>
- *
- * <p>If both an algorithm name and a package provider are specified, the system
- * will determine if there is an implementation of the algorithm in the package
- * requested, and throw an exception if there is not.</p>
- *
- * <p>A <code>Signature</code> object can be used to generate and verify digital
- * signatures.</p>
- *
- * <p>There are three phases to the use of a <code>Signature</code> object for
- * either signing data or verifying a signature:</p>
- *
+ * <code>Signature</code> is used to provide an interface to digital signature
+ * algorithms. Digital signatures provide authentication and data integrity of
+ * digital data.
+ * 
+ * <p>The GNU provider provides the NIST standard DSA which uses DSA and SHA-1.
+ * It can be specified by SHA/DSA, SHA-1/DSA or its OID. If the RSA signature
+ * algorithm is provided then it could be MD2/RSA. MD5/RSA, or SHA-1/RSA. The
+ * algorithm must be specified because there is no default.</p>
+ * 
+ * <p>Signature provides implementation-independent algorithms which are
+ * requested by the user through the <code>getInstance()<?code> methods. It can
+ * be requested by specifying just the algorithm name or by specifying both the
+ * algorithm name and provider name.</p>
+ * 
+ * <p>The three phases of using <code>Signature</code> are:</p>
+ * 
  * <ol>
- * <li>Initialization, with either
+ *   <li>Initializing:
  *     <ul>
- *     <li>a public key, which initializes the signature for verification
- *         (see <code>initVerify()</code>), or</li>
- *     <li>a private key (and optionally a Secure Random Number Generator),
- *         which initializes the signature for signing (see
- *         {@link #initSign(PrivateKey)} and {@link #initSign(PrivateKey, SecureRandom)}
- *         ).</li>
- *     </ul></li>
- * <li>Updating<br/>
- *     Depending on the type of initialization, this will update the bytes to
- *     be signed or verified. See the update methods.<br/></li>
- * <li>Signing or Verifying a signature on all updated bytes. See the
- *     <code>sign()</code> methods and the <code>verify()</code> method.</li>
- *  </ol>
- *
- * <p>Note that this class is abstract and extends from {@link SignatureSpi} for
- * historical reasons. Application developers should only take notice of the
- * methods defined in this <code>Signature</code> class; all the methods in the
- * superclass are intended for cryptographic service providers who wish to
- * supply their own implementations of digital signature algorithms.
+ *       <li>It must be initialized with a private key for signing.</li>
+ *       <li>It must be initialized with a public key for verifying.</li>
+ *   </li>
+ *   
+ *   <li>Updating:
+ *   <p>Update the bytes for signing or verifying with calls to update.</p>
+ *   </li>
+ *   
+ *   <li>Signing or Verify the signature on the currently stored bytes by
+ *   calling sign or verify.</li>
+ * </ol>
  *
  * @author Mark Benvenuto  (ivymccough@worldnet.att.net)
  */
@@ -114,38 +84,38 @@ public abstract class Signature extends SignatureSpi
   private static final String SIGNATURE = "Signature";
 
   /**
-   * Possible <code>state</code> value, signifying that this signature object
-   * has not yet been initialized.
+   * Possible state value which signifies that this instance has not yet been
+   * initialized.
    */
   protected static final int UNINITIALIZED = 0;
 
-  // Constructor.
-  // ------------------------------------------------------------------------
-
   /**
-   * Possible <code>state</code> value, signifying that this signature object
-   * has been initialized for signing.
+   * Possible state value which signifies that this instance has been
+   * initialized for signing purposes.
    */
   protected static final int SIGN = 2;
 
   /**
-   * Possible <code>state</code> value, signifying that this signature object
-   * has been initialized for verification.
+   * Possible state value which signifies that this instance has been
+   * initialized for verification purposes.
    */
   protected static final int VERIFY = 3;
 
-  /** Current state of this signature object. */
+  /** Current sate of this instance. */
   protected int state = UNINITIALIZED;
 
   private String algorithm;
   Provider provider;
 
+  // Constructor.
+  // ------------------------------------------------------------------------
+
   /**
-   * Creates a <code>Signature</code> object for the specified algorithm.
-   *
-   * @param algorithm the standard string name of the algorithm. See Appendix A
-   * in the Java Cryptography Architecture API Specification &amp; Reference for
-   * information about standard algorithm names.
+   * Constructs a new <code>Signature</code> instance for a designated digital
+   * signature algorithm.
+   * 
+   * @param algorithm
+   *          the algorithm to use.
    */
   protected Signature(String algorithm)
   {
@@ -154,19 +124,14 @@ public abstract class Signature extends SignatureSpi
   }
 
   /**
-   * Generates a <code>Signature</code> object that implements the specified
-   * digest algorithm. If the default provider package provides an
-   * implementation of the requested digest algorithm, an instance of
-   * <code>Signature</code> containing that implementation is returned. If the
-   * algorithm is not available in the default package, other packages are
-   * searched.
-   *
-   * @param algorithm the standard name of the algorithm requested. See Appendix
-   * A in the Java Cryptography Architecture API Specification &amp; Reference
-   * for information about standard algorithm names.
-   * @return the new Signature object.
-   * @throws NoSuchAlgorithmException if the algorithm is not available in the
-   * environment.
+   * Returns an instance of <code>Signature</code> representing the specified
+   * signature.
+   * 
+   * @param algorithm
+   *          the algorithm to use.
+   * @return a new instance repesenting the desired algorithm.
+   * @throws NoSuchAlgorithmException
+   *           if the algorithm is not implemented by any provider.
    */
   public static Signature getInstance(String algorithm)
     throws NoSuchAlgorithmException
@@ -188,22 +153,20 @@ public abstract class Signature extends SignatureSpi
   }
 
   /**
-   * Generates a <code>Signature</code> object implementing the specified
-   * algorithm, as supplied from the specified provider, if such an algorithm
-   * is available from the provider.
-   *
-   * @param algorithm the name of the algorithm requested. See Appendix A in
-   * the Java Cryptography Architecture API Specification &amp; Reference for
-   * information about standard algorithm names.
-   * @param provider the name of the provider.
-   * @return the new <code>Signature</code> object.
-   * @throws NoSuchAlgorithmException if the algorithm is not available in the
-   * package supplied by the requested provider.
-   * @throws NoSuchProviderException if the provider is not available in the
-   * environment.
-   * @throws IllegalArgumentException if the provider name is <code>null</code>
-   * or empty.
-   * @see Provider
+   * Returns an instance of <code>Signature</code> representing the specified
+   * signature from the named provider.
+   * 
+   * @param algorithm
+   *          the algorithm to use.
+   * @param provider
+   *          the name of the provider to use.
+   * @return a new instance repesenting the desired algorithm.
+   * @throws IllegalArgumentException if <code>provider</code> is
+   *           <code>null</code> or is an empty string.
+   * @throws NoSuchProviderException
+   *           if the named provider was not found.
+   * @throws NoSuchAlgorithmException
+   *           if the algorithm is not implemented by the named provider.
    */
   public static Signature getInstance(String algorithm, String provider)
     throws NoSuchAlgorithmException, NoSuchProviderException
@@ -219,22 +182,16 @@ public abstract class Signature extends SignatureSpi
   }
 
   /**
-   * Generates a <code>Signature</code> object implementing the specified
-   * algorithm, as supplied from the specified provider, if such an algorithm
-   * is available from the provider. Note: the provider doesn't have to be
-   * registered.
-   *
-   * @param algorithm the name of the algorithm requested. See Appendix A in
-   * the Java Cryptography Architecture API Specification &amp; Reference for
-   * information about standard algorithm names.
-   * @param provider the provider.
-   * @return the new <code>Signature</code> object.
-   * @throws NoSuchAlgorithmException if the <code>algorithm</code> is not
-   * available in the package supplied by the requested <code>provider</code>.
-   * @throws IllegalArgumentException if the <code>provider</code> is
-   * <code>null</code>.
-   * @since 1.4
-   * @see Provider
+   * Returns an instance of <code>Signature</code> representing the specified
+   * signature from the specified {@link Provider}.
+   * 
+   * @param algorithm
+   *          the algorithm to use.
+   * @param provider
+   *          the {@link Provider} to use.
+   * @return a new instance repesenting the desired algorithm.
+   * @throws NoSuchAlgorithmException
+   *           if the algorithm is not implemented by the {@link Provider}.
    */
   public static Signature getInstance(String algorithm, Provider provider)
     throws NoSuchAlgorithmException
@@ -271,9 +228,9 @@ public abstract class Signature extends SignatureSpi
   }
 
   /**
-   * Returns the provider of this signature object.
-   *
-   * @return the provider of this signature object.
+   * Returns the {@link Provider} of this instance.
+   * 
+   * @return the {@link Provider} of this instance.
    */
   public final Provider getProvider()
   {
@@ -281,12 +238,12 @@ public abstract class Signature extends SignatureSpi
   }
 
   /**
-   * Initializes this object for verification. If this method is called again
-   * with a different argument, it negates the effect of this call.
-   *
-   * @param publicKey the public key of the identity whose signature is going
-   * to be verified.
-   * @throws InvalidKeyException if the key is invalid.
+   * Initializes this instance with the public key for verification purposes.
+   * 
+   * @param publicKey
+   *          the public key to verify with.
+   * @throws InvalidKeyException
+   *           if the key is invalid.
    */
   public final void initVerify(PublicKey publicKey) throws InvalidKeyException
   {
@@ -295,20 +252,16 @@ public abstract class Signature extends SignatureSpi
   }
 
   /**
-   * <p>Initializes this object for verification, using the public key from the
-   * given certificate.</p>
-   *
-   * <p>If the certificate is of type <i>X.509</i> and has a <i>key usage</i>
-   * extension field marked as <i>critical</i>, and the value of the <i>key
-   * usage</i> extension field implies that the public key in the certificate
-   * and its corresponding private key are not supposed to be used for digital
-   * signatures, an {@link InvalidKeyException} is thrown.</p>
-   *
-   * @param certificate the certificate of the identity whose signature is
-   * going to be verified.
-   * @throws InvalidKeyException if the public key in the certificate is not
-   * encoded properly or does not include required parameter information or
-   * cannot be used for digital signature purposes.
+   * Verify a signature with a designated {@link Certificate}. This is a FIPS
+   * 140-1 compatible method since it verifies a signature with a certificate.
+   * 
+   * <p>If the {@link Certificate} is an X.509 one, has a <i>KeyUsage</i>
+   * parameter and that parameter indicates this key is not to be used for
+   * signing then an exception is thrown.</p>
+   * 
+   * @param certificate
+   *          a {@link Certificate} containing a public key to verify with.
+   * @throws InvalidKeyException if the key is invalid.
    */
   public final void initVerify(Certificate certificate)
     throws InvalidKeyException
@@ -326,12 +279,12 @@ public abstract class Signature extends SignatureSpi
   }
 
   /**
-   * Initialize this object for signing. If this method is called again with a
-   * different argument, it negates the effect of this call.
-   *
-   * @param privateKey the private key of the identity whose signature is going
-   * to be generated.
-   * @throws InvalidKeyException if the key is invalid.
+   * Initializes this class with the private key for signing purposes.
+   * 
+   * @param privateKey
+   *          the private key to sign with.
+   * @throws InvalidKeyException
+   *           if the key is invalid.
    */
   public final void initSign(PrivateKey privateKey) throws InvalidKeyException
   {
@@ -340,13 +293,15 @@ public abstract class Signature extends SignatureSpi
   }
 
   /**
-   * Initialize this object for signing. If this method is called again with a
-   * different argument, it negates the effect of this call.
-   *
-   * @param privateKey the private key of the identity whose signature is going
-   * to be generated.
-   * @param random the source of randomness for this signature.
-   * @throws InvalidKeyException if the key is invalid.
+   * Initializes this class with the private key and source of randomness for
+   * signing purposes.
+   * 
+   * @param privateKey
+   *          the private key to sign with.
+   * @param random
+   *          the {@link SecureRandom} to use.
+   * @throws InvalidKeyException
+   *           if the key is invalid.
    */
   public final void initSign(PrivateKey privateKey, SecureRandom random)
     throws InvalidKeyException
@@ -356,18 +311,12 @@ public abstract class Signature extends SignatureSpi
   }
 
   /**
-   * <p>Returns the signature bytes of all the data updated. The format of the
-   * signature depends on the underlying signature scheme.</p>
-   *
-   * <p>A call to this method resets this signature object to the state it was
-   * in when previously initialized for signing via a call to
-   * <code>initSign(PrivateKey)</code>. That is, the object is reset and
-   * available to generate another signature from the same signer, if desired,
-   * via new calls to <code>update()</code> and <code>sign()</code>.</p>
-   *
-   * @return the signature bytes of the signing operation's result.
-   * @throws SignatureException if this signature object is not initialized
-   * properly.
+   * Returns the signature bytes of all the data fed to this instance. The
+   * format of the output depends on the underlying signature algorithm.
+   * 
+   * @return the signature bytes.
+   * @throws SignatureException
+   *           if the engine is not properly initialized.
    */
   public final byte[] sign() throws SignatureException
   {
@@ -378,21 +327,27 @@ public abstract class Signature extends SignatureSpi
   }
 
   /**
-   * <p>Finishes the signature operation and stores the resulting signature
-   * bytes in the provided buffer <code>outbuf</code>, starting at <code>offset
-   * </code>. The format of the signature depends on the underlying signature
-   * scheme.</p>
-   *
-   * <p>This signature object is reset to its initial state (the state it was
-   * in after a call to one of the <code>initSign()</code> methods) and can be
-   * reused to generate further signatures with the same private key.</p>
-   *
-   * @param outbuf buffer for the signature result.
-   * @param offset offset into outbuf where the signature is stored.
-   * @param len number of bytes within outbuf allotted for the signature.
-   * @return the number of bytes placed into outbuf.
-   * @throws SignatureException if an error occurs or len is less than the
-   * actual signature length.
+   * Generates signature bytes of all the data fed to this instance and stores
+   * it in the designated array. The format of the result depends on the
+   * underlying signature algorithm.
+   * 
+   * <p>After calling this method, the instance is reset to its initial state
+   * and can then be used to generate additional signatures.</p>
+   * 
+   * <p><b>IMPLEMENTATION NOTE:</b> Neither this method nor the GNU provider
+   * will return partial digests. If <code>len</code> is less than the
+   * signature length, this method will throw a {@link SignatureException}. If
+   * it is greater than or equal then it is ignored.</p>
+   * 
+   * @param outbuf
+   *          array of bytes of where to store the resulting signature bytes.
+   * @param offset
+   *          the offset to start at in the array.
+   * @param len
+   *          the number of the bytes to use in the array.
+   * @return the real number of bytes used.
+   * @throws SignatureException
+   *           if the engine is not properly initialized.
    * @since 1.2
    */
   public final int sign(byte[] outbuf, int offset, int len)
@@ -405,20 +360,14 @@ public abstract class Signature extends SignatureSpi
   }
 
   /**
-   * <p>Verifies the passed-in signature.</p>
-   *
-   * <p>A call to this method resets this signature object to the state it was
-   * in when previously initialized for verification via a call to
-   * <code>initVerify(PublicKey)</code>. That is, the object is reset and
-   * available to verify another signature from the identity whose public key
-   * was specified in the call to <code>initVerify()</code>.</p>
-   *
-   * @param signature the signature bytes to be verified.
-   * @return <code>true</code> if the signature was verified, <code>false</code>
-   * if not.
-   * @throws SignatureException if this signature object is not initialized
-   * properly, or the passed-in signature is improperly encoded or of the wrong
-   * type, etc.
+   * Verifies a designated signature.
+   * 
+   * @param signature
+   *          the signature bytes to verify.
+   * @return <code>true</code> if verified, <code>false</code> otherwise.
+   * @throws SignatureException
+   *           if the engine is not properly initialized or the signature does
+   *           not check.
    */
   public final boolean verify(byte[]signature) throws SignatureException
   {
@@ -429,28 +378,24 @@ public abstract class Signature extends SignatureSpi
   }
 
   /**
-   * <p>Verifies the passed-in <code>signature</code> in the specified array of
-   * bytes, starting at the specified <code>offset</code>.</p>
-   *
-   * <p>A call to this method resets this signature object to the state it was
-   * in when previously initialized for verification via a call to
-   * <code>initVerify(PublicKey)</code>. That is, the object is reset and
-   * available to verify another signature from the identity whose public key
-   * was specified in the call to <code>initVerify()</code>.</p>
-   *
-   * @param signature the signature bytes to be verified.
-   * @param offset the offset to start from in the array of bytes.
-   * @param length the number of bytes to use, starting at offset.
-   * @return <code>true</code> if the signature was verified, <code>false</code>
-   * if not.
-   * @throws SignatureException if this signature object is not initialized
-   * properly, or the passed-in <code>signature</code> is improperly encoded or
-   * of the wrong type, etc.
-   * @throws IllegalArgumentException if the <code>signature</code> byte array
-   * is <code>null</code>, or the <code>offset</code> or <code>length</code> is
-   * less than <code>0</code>, or the sum of the <code>offset</code> and
-   * <code>length</code> is greater than the length of the <code>signature</code>
-   * byte array.
+   * Verifies a designated signature.
+   * 
+   * @param signature
+   *          the signature bytes to verify.
+   * @param offset
+   *          the offset to start at in the array.
+   * @param length
+   *          the number of the bytes to use from the array.
+   * @return <code>true</code> if verified, <code>false</code> otherwise.
+   * @throws IllegalArgumentException
+   *           if the <code>signature</code> byte array is <code>null</code>,
+   *           or the <code>offset</code> or <code>length</code> is less
+   *           than <code>0</code>, or the sum of the <code>offset</code>
+   *           and <code>length</code> is greater than the length of the
+   *           <code>signature</code> byte array.
+   * @throws SignatureException
+   *           if the engine is not properly initialized or the signature does
+   *           not check.
    */
   public final boolean verify(byte[] signature, int offset, int length)
     throws SignatureException
@@ -471,11 +416,12 @@ public abstract class Signature extends SignatureSpi
   }
 
   /**
-   * Updates the data to be signed or verified by a byte.
-   *
-   * @param b the byte to use for the update.
-   * @throws SignatureException if this signature object is not initialized
-   * properly.
+   * Updates the data to be signed or verified with the specified byte.
+   * 
+   * @param b
+   *          the byte to update with.
+   * @throws SignatureException
+   *           if the engine is not properly initialized.
    */
   public final void update(byte b) throws SignatureException
   {
@@ -486,12 +432,12 @@ public abstract class Signature extends SignatureSpi
   }
 
   /**
-   * Updates the data to be signed or verified, using the specified array of
-   * bytes.
-   *
-   * @param data the byte array to use for the update.
-   * @throws SignatureException if this signature object is not initialized
-   * properly.
+   * Updates the data to be signed or verified with the specified bytes.
+   * 
+   * @param data
+   *          the array of bytes to use.
+   * @throws SignatureException
+   *           if the engine is not properly initialized.
    */
   public final void update(byte[]data) throws SignatureException
   {
@@ -502,14 +448,16 @@ public abstract class Signature extends SignatureSpi
   }
 
   /**
-   * Updates the data to be signed or verified, using the specified array of
-   * bytes, starting at the specified offset.
-   *
-   * @param data the array of bytes.
-   * @param off the offset to start from in the array of bytes.
-   * @param len the number of bytes to use, starting at offset.
-   * @throws SignatureException if this signature object is not initialized
-   * properly.
+   * Updates the data to be signed or verified with the specified bytes.
+   * 
+   * @param data
+   *          an array of bytes to use.
+   * @param off
+   *          the offset to start at in the array.
+   * @param len
+   *          the number of bytes to use from the array.
+   * @throws SignatureException
+   *           if the engine is not properly initialized.
    */
   public final void update(byte[]data, int off, int len)
     throws SignatureException
@@ -521,9 +469,10 @@ public abstract class Signature extends SignatureSpi
   }
 
   /**
-   * Returns the name of the algorithm for this signature object.
-   *
-   * @return the name of the algorithm for this signature object.
+   * Returns the name of the algorithm currently used. The names of algorithms
+   * are usually SHA/DSA or SHA/RSA.
+   * 
+   * @return name of algorithm.
    */
   public final String getAlgorithm()
   {
@@ -531,11 +480,9 @@ public abstract class Signature extends SignatureSpi
   }
 
   /**
-   * Returns a string representation of this signature object, providing
-   * information that includes the state of the object and the name of the
-   * algorithm used.
-   *
-   * @return a string representation of this signature object.
+   * Returns a rstring representation of this instance.
+   * 
+   * @return a rstring representation of this instance.
    */
   public String toString()
   {
@@ -543,22 +490,16 @@ public abstract class Signature extends SignatureSpi
   }
 
   /**
-   * Sets the specified algorithm parameter to the specified value. This method
-   * supplies a general-purpose mechanism through which it is possible to set
-   * the various parameters of this object. A parameter may be any settable
-   * parameter for the algorithm, such as a parameter size, or a source of
-   * random bits for signature generation (if appropriate), or an indication of
-   * whether or not to perform a specific but optional computation. A uniform
-   * algorithm-specific naming scheme for each parameter is desirable but left
-   * unspecified at this time.
-   *
-   * @param param the string identifier of the parameter.
-   * @param value the parameter value.
-   * @throws InvalidParameterException if param is an invalid parameter for this
-   * signature algorithm engine, the parameter is already set and cannot be set
-   * again, a security exception occurs, and so on.
-   * @see #getParameter(String)
-   * @deprecated Use setParameter(AlgorithmParameterSpec).
+   * Sets the specified algorithm parameter to the specified value.
+   * 
+   * @param param
+   *          the parameter name.
+   * @param value
+   *          the parameter value.
+   * @throws InvalidParameterException
+   *           if the parameter is invalid, the parameter is already set and
+   *           can not be changed, a security exception occured, etc.
+   * @deprecated use the other setParameter
    */
   public final void setParameter(String param, Object value)
     throws InvalidParameterException
@@ -567,12 +508,16 @@ public abstract class Signature extends SignatureSpi
   }
 
   /**
-   * Initializes this signature engine with the specified parameter set.
-   *
-   * @param params the parameters.
-   * @throws InvalidAlgorithmParameterException if the given parameters are
-   * inappropriate for this signature engine.
-   * @see #getParameters()
+   * Sets the signature engine with the specified {@link AlgorithmParameterSpec}.
+   * 
+   * <p>By default, and unless overriden by the concrete SPI, this method always
+   * throws an {@link UnsupportedOperationException}.</p>
+   * 
+   * @param params
+   *          the parameters to use for intializing this instance.
+   * @throws InvalidParameterException
+   *           if the parameter is invalid, the parameter is already set and
+   *           cannot be changed, a security exception occured, etc.
    */
   public final void setParameter(AlgorithmParameterSpec params)
     throws InvalidAlgorithmParameterException
@@ -581,17 +526,11 @@ public abstract class Signature extends SignatureSpi
   }
 
   /**
-   * <p>Returns the parameters used with this signature object.</p>
-   *
-   * <p>The returned parameters may be the same that were used to initialize
-   * this signature, or may contain a combination of default and randomly
-   * generated parameter values used by the underlying signature implementation
-   * if this signature requires algorithm parameters but was not initialized
-   * with any.
-   *
-   * @return the parameters used with this signature, or <code>null</code> if
-   * this signature does not use any parameters.
-   * @see #setParameter(AlgorithmParameterSpec)
+   * Return the parameters of the algorithm used in this instance as an
+   * {@link AlgorithmParameters}.
+   * 
+   * @return the parameters used with this instance, or <code>null</code> if
+   *         this instance does not use any parameters.
    */
   public final AlgorithmParameters getParameters()
   {
@@ -599,22 +538,14 @@ public abstract class Signature extends SignatureSpi
   }
 
   /**
-   * Gets the value of the specified algorithm parameter. This method supplies
-   * a general-purpose mechanism through which it is possible to get the various
-   * parameters of this object. A parameter may be any settable parameter for
-   * the algorithm, such as a parameter size, or a source of random bits for
-   * signature generation (if appropriate), or an indication of whether or not
-   * to perform a specific but optional computation. A uniform
-   * algorithm-specific naming scheme for each parameter is desirable but left
-   * unspecified at this time.
-   *
-   * @param param the string name of the parameter.
-   * @return the object that represents the parameter value, or null if there
-   * is none.
-   * @throws InvalidParameterException if param is an invalid parameter for this
-   * engine, or another exception occurs while trying to get this parameter.
-   * @see #setParameter(String, Object)
-   * @deprecated
+   * Returns the value for the specified algorithm parameter.
+   * 
+   * @param param
+   *          the parameter name.
+   * @return the parameter value.
+   * @throws InvalidParameterException
+   *           if the parameter is invalid.
+   * @deprecated use the other getParameter
    */
   public final Object getParameter(String param)
     throws InvalidParameterException
@@ -623,11 +554,11 @@ public abstract class Signature extends SignatureSpi
   }
 
   /**
-   * Returns a clone if the implementation is cloneable.
-   *
-   * @return a clone if the implementation is cloneable.
-   * @throws CloneNotSupportedException if this is called on an implementation
-   * that does not support {@link Cloneable}.
+   * Returns a clone of this instance.
+   * 
+   * @return a clone of this instace.
+   * @throws CloneNotSupportedException
+   *           if the implementation does not support cloning.
    */
   public Object clone() throws CloneNotSupportedException
   {
diff --git a/java/security/SignatureSpi.java b/java/security/SignatureSpi.java
index 471a73d17..25d49dedd 100644
--- a/java/security/SignatureSpi.java
+++ b/java/security/SignatureSpi.java
@@ -40,14 +40,10 @@ package java.security;
 import java.security.spec.AlgorithmParameterSpec;
 
 /**
- * <p>This class defines the <i>Service Provider Interface (SPI)</i> for the
- * {@link Signature} class, which is used to provide the functionality of a
+ * <code>SignatureSpi</code> defines the Service Provider Interface (SPI) for
+ * the {@link Signature} class. The signature class provides an interface to a
  * digital signature algorithm. Digital signatures are used for authentication
- * and integrity assurance of digital data.</p>
- *
- * <p>All the abstract methods in this class must be implemented by each
- * cryptographic service provider who wishes to supply the implementation of a
- * particular signature algorithm.
+ * and integrity of data.
  *
  * @author Mark Benvenuto (ivymccough@worldnet.att.net)
  * @since 1.2
@@ -55,50 +51,51 @@ import java.security.spec.AlgorithmParameterSpec;
  */
 public abstract class SignatureSpi
 {
-  /** Application-specified source of randomness. */
+  /** Source of randomness. */
   protected SecureRandom appRandom;
 
+  /**
+   * Creates a new instance of <code>SignatureSpi</code>.
+   */
   public SignatureSpi()
   {
     appRandom = null;
   }
 
   /**
-   * Initializes this signature object with the specified public key for
-   * verification operations.
-   *
-   * @param publicKey the public key of the identity whose signature is going
-   * to be verified.
-   * @throws InvalidKeyException if the key is improperly encoded, parameters
-   * are missing, and so on.
+   * Initializes this instance with the public key for verification purposes.
+   * 
+   * @param publicKey
+   *          the public key to verify with.
+   * @throws InvalidKeyException
+   *           if the key is invalid.
    */
   protected abstract void engineInitVerify(PublicKey publicKey)
     throws InvalidKeyException;
 
   /**
-   * Initializes this signature object with the specified private key for
-   * signing operations.
-   *
-   * @param privateKey the private key of the identity whose signature will be
-   * generated.
-   * @throws InvalidKeyException if the key is improperly encoded, parameters
-   * are missing, and so on.
+   * Initializes this instance with the private key for signing purposes.
+   * 
+   * @param privateKey
+   *          the private key to sign with.
+   * @throws InvalidKeyException
+   *           if the key is invalid.
    */
   protected abstract void engineInitSign(PrivateKey privateKey)
     throws InvalidKeyException;
 
   /**
-   * <p>Initializes this signature object with the specified private key and
-   * source of randomness for signing operations.</p>
-   *
-   * <p>This concrete method has been added to this previously-defined abstract
-   * class. (For backwards compatibility, it cannot be abstract.)</p>
-   *
-   * @param privateKey the private key of the identity whose signature will be
-   * generated.
-   * @param random the source of randomness.
-   * @throws InvalidKeyException if the key is improperly encoded, parameters
-   * are missing, and so on.
+   * Initializes this instance with the private key and source of randomness for
+   * signing purposes.
+   * 
+   * <p>This method cannot be abstract for backward compatibility reasons.</p>
+   * 
+   * @param privateKey
+   *          the private key to sign with.
+   * @param random
+   *          the {@link SecureRandom} to use.
+   * @throws InvalidKeyException
+   *           if the key is invalid.
    * @since 1.2
    */
   protected void engineInitSign(PrivateKey privateKey, SecureRandom random)
@@ -109,57 +106,63 @@ public abstract class SignatureSpi
   }
 
   /**
-   * Updates the data to be signed or verified using the specified byte.
-   *
-   * @param b the byte to use for the update.
-   * @throws SignatureException if the engine is not initialized properly.
+   * Updates the data to be signed or verified with the specified byte.
+   * 
+   * @param b
+   *          byte to update with.
+   * @throws SignatureException
+   *           if the engine is not properly initialized.
    */
   protected abstract void engineUpdate(byte b) throws SignatureException;
 
   /**
-   * Updates the data to be signed or verified, using the specified array of
-   * bytes, starting at the specified offset.
-   *
-   * @param b the array of bytes.
-   * @param off the offset to start from in the array of bytes.
-   * @param len the number of bytes to use, starting at offset.
-   * @throws SignatureException if the engine is not initialized properly.
+   * Updates the data to be signed or verified with the specified bytes.
+   * 
+   * @param b
+   *          the array of bytes to use.
+   * @param off
+   *          the offset to start at in the array.
+   * @param len
+   *          the number of the bytes to use from the array.
+   * @throws SignatureException
+   *           if the engine is not properly initialized.
    */
   protected abstract void engineUpdate(byte[] b, int off, int len)
     throws SignatureException;
 
   /**
-   * Returns the signature bytes of all the data updated so far. The format of
-   * the signature depends on the underlying signature scheme.
-   *
-   * @return the signature bytes of the signing operation's result.
-   * @throws SignatureException if the engine is not initialized properly.
+   * Returns the signature bytes of all the data fed to this instance. The
+   * format of the output depends on the underlying signature algorithm.
+   * 
+   * @return the signature bytes.
+   * @throws SignatureException
+   *           if the engine is not properly initialized.
    */
   protected abstract byte[] engineSign() throws SignatureException;
 
   /**
-   * <p>Finishes this signature operation and stores the resulting signature
-   * bytes in the provided buffer <code>outbuf</code>, starting at <code>offset
-   * </code>. The format of the signature depends on the underlying signature
-   * scheme.</p>
-   *
-   * <p>The signature implementation is reset to its initial state (the state it
-   * was in after a call to one of the <code>engineInitSign()</code> methods)
-   * and can be reused to generate further signatures with the same private key.
-   * This method should be abstract, but we leave it concrete for binary
-   * compatibility. Knowledgeable providers should override this method.</p>
-   *
-   * @param outbuf buffer for the signature result.
-   * @param offset offset into outbuf where the signature is stored.
-   * @param len number of bytes within outbuf allotted for the signature. Both
-   * this default implementation and the <b>GNU</b> provider do not return
-   * partial digests. If the value of this parameter is less than the actual
-   * signature length, this method will throw a {@link SignatureException}. This
-   * parameter is ignored if its value is greater than or equal to the actual
-   * signature length.
-   * @return the number of bytes placed into <code>outbuf</code>.
-   * @throws SignatureException if an error occurs or len is less than the
-   * actual signature length.
+   * Generates signature bytes of all the data fed to this instance and stores
+   * the result in the designated array. The format of the output depends on
+   * the underlying signature algorithm.
+   * 
+   * <p>This method cannot be abstract for backward compatibility reasons.
+   * After calling this method, the signature is reset to its initial state and
+   * can be used to generate additional signatures.</p>
+   * 
+   * <p><b>IMPLEMENTATION NOTE:</b>: Neither this method nor the GNU provider
+   * will return partial digests. If <code>len</code> is less than the
+   * signature length, this method will throw a {@link SignatureException}. If
+   * it is greater than or equal then it is ignored.</p>
+   * 
+   * @param outbuf
+   *          the array of bytes to store the result in.
+   * @param offset
+   *          the offset to start at in the array.
+   * @param len
+   *          the number of the bytes to use in the array.
+   * @return the real number of bytes used.
+   * @throws SignatureException
+   *           if the engine is not properly initialized.
    * @since 1.2
    */
   protected int engineSign(byte[] outbuf, int offset, int len)
@@ -174,31 +177,32 @@ public abstract class SignatureSpi
   }
 
   /**
-   * Verifies the passed-in signature.
-   *
-   * @param sigBytes the signature bytes to be verified.
-   * @return <code>true</code> if the signature was verified, <code>false</code>
-   * if not.
-   * @throws SignatureException if the engine is not initialized properly, or
-   * the passed-in signature is improperly encoded or of the wrong type, etc.
+   * Verifies a designated signature.
+   * 
+   * @param sigBytes
+   *          the signature bytes to verify.
+   * @return <code>true</code> if verified, <code>false</code> otherwise.
+   * @throws SignatureException
+   *           if the engine is not properly initialized or if it is the wrong
+   *           signature.
    */
   protected abstract boolean engineVerify(byte[] sigBytes)
     throws SignatureException;
 
   /**
-   * <p>Verifies the passed-in <code>signature</code> in the specified array of
-   * bytes, starting at the specified <code>offset</code>.</p>
-   *
-   * <p>Note: Subclasses should overwrite the default implementation.</p>
-   *
-   * @param sigBytes the signature bytes to be verified.
-   * @param offset the offset to start from in the array of bytes.
-   * @param length the number of bytes to use, starting at offset.
-   * @return <code>true</code> if the signature was verified, <code>false</code>
-   * if not.
-   * @throws SignatureException if the engine is not initialized properly, or
-   * the passed-in <code>signature</code> is improperly encoded or of the wrong
-   * type, etc.
+   * Convenience method which calls the method with the same name and one
+   * argument after copying the designated bytes into a temporary byte array.
+   * Subclasses may override this method for performance reasons.
+   * 
+   * @param sigBytes
+   *          the array of bytes to use.
+   * @param offset
+   *          the offset to start from in the array of bytes.
+   * @param length
+   *          the number of bytes to use, starting at offset.
+   * @return <code>true</code> if verified, <code>false</code> otherwise.
+   * @throws SignatureException
+   *           if the engine is not properly initialized.
    */
   protected boolean engineVerify(byte[] sigBytes, int offset, int length)
     throws SignatureException
@@ -209,35 +213,32 @@ public abstract class SignatureSpi
   }
 
   /**
-   * Sets the specified algorithm parameter to the specified value. This method
-   * supplies a general-purpose mechanism through which it is possible to set
-   * the various parameters of this object. A parameter may be any settable
-   * parameter for the algorithm, such as a parameter size, or a source of
-   * random bits for signature generation (if appropriate), or an indication of
-   * whether or not to perform a specific but optional computation. A uniform
-   * algorithm-specific naming scheme for each parameter is desirable but left
-   * unspecified at this time.
-   *
-   * @param param the string identifier of the parameter.
-   * @param value the parameter value.
-   * @throws InvalidParameterException if <code>param</code> is an invalid
-   * parameter for this signature algorithm engine, the parameter is already set
-   * and cannot be set again, a security exception occurs, and so on.
-   * @deprecated Replaced by engineSetParameter(AlgorithmParameterSpec).
+   * Sets the specified algorithm parameter to the specified value.
+   * 
+   * @param param
+   *          the parameter name.
+   * @param value
+   *          the parameter value.
+   * @throws InvalidParameterException
+   *           if the parameter invalid, the parameter is already set and
+   *           cannot be changed, a security exception occured, etc.
+   * @deprecated use the other setParameter.
    */
   protected abstract void engineSetParameter(String param, Object value)
     throws InvalidParameterException;
 
   /**
-   * This method is overridden by providers to initialize this signature engine
-   * with the specified parameter set.
-   *
-   * @param params the parameters.
-   * @throws UnsupportedOperationException if this method is not overridden by
-   * a provider.
-   * @throws InvalidAlgorithmParameterException if this method is overridden by
-   * a provider and the the given parameters are inappropriate for this
-   * signature engine.
+   * Sets the signature engine with the specified {@link AlgorithmParameterSpec}.
+   * 
+   * <p>This method cannot be abstract for backward compatibility reasons. By
+   * default it always throws {@link UnsupportedOperationException} unless
+   * overridden.</p>
+   * 
+   * @param params
+   *          the parameters.
+   * @throws InvalidParameterException
+   *           if the parameter is invalid, the parameter is already set and
+   *           cannot be changed, a security exception occured, etc.
    */
   protected void engineSetParameter(AlgorithmParameterSpec params)
     throws InvalidAlgorithmParameterException
@@ -246,20 +247,16 @@ public abstract class SignatureSpi
   }
 
   /**
-   * <p>This method is overridden by providers to return the parameters used
-   * with this signature engine, or <code>null</code> if this signature engine
-   * does not use any parameters.</p>
-   *
-   * <p>The returned parameters may be the same that were used to initialize
-   * this signature engine, or may contain a combination of default and randomly
-   * generated parameter values used by the underlying signature implementation
-   * if this signature engine requires algorithm parameters but was not
-   * initialized with any.</p>
-   *
-   * @return the parameters used with this signature engine, or <code>null</code>
-   * if this signature engine does not use any parameters.
-   * @throws UnsupportedOperationException if this method is not overridden by
-   * a provider.
+   * The default implementaion of this method always throws a
+   * {@link UnsupportedOperationException}. It MUST be overridden by concrete
+   * implementations to return the appropriate {@link AlgorithmParameters} for
+   * this signature engine (or <code>null</code> when that engine does not use
+   * any parameters.
+   * 
+   * @return the parameters used with this signature engine, or
+   *         <code>null</code> if it does not use any parameters.
+   * @throws UnsupportedOperationException
+   *           always.
    */
   protected AlgorithmParameters engineGetParameters()
   {
@@ -267,33 +264,24 @@ public abstract class SignatureSpi
   }
 
   /**
-   * Gets the value of the specified algorithm parameter. This method supplies
-   * a general-purpose mechanism through which it is possible to get the various
-   * parameters of this object. A parameter may be any settable parameter for
-   * the algorithm, such as a parameter size, or a source of random bits for
-   * signature generation (if appropriate), or an indication of whether or not
-   * to perform a specific but optional computation. A uniform algorithm-specific
-   * naming scheme for each parameter is desirable but left unspecified at this
-   * time.
-   *
-   * @param param the string name of the parameter.
-   * @return the object that represents the parameter value, or <code>null</code>
-   * if there is none.
-   * @throws InvalidParameterException if <code>param</code> is an invalid
-   * parameter for this engine, or another exception occurs while trying to get
-   * this parameter.
-   * @deprecated
+   * Returns the value for the specified algorithm parameter.
+   * 
+   * @param param
+   *          the parameter name.
+   * @return the parameter value.
+   * @throws InvalidParameterException
+   *           if the parameter is invalid.
+   * @deprecated use the other getParameter
    */
   protected abstract Object engineGetParameter(String param)
     throws InvalidParameterException;
 
   /**
-   * Returns a clone if the implementation is cloneable.
-   *
-   * @return a clone if the implementation is cloneable.
-   * @throws CloneNotSupportedException if this is called on an implementation
-   * that does not support {@link Cloneable}.
-   * @see Cloneable
+   * Returns a clone of this instance.
+   * 
+   * @return a clone of this instance.
+   * @throws CloneNotSupportedException
+   *           if the implementation does not support cloning.
    */
   public Object clone() throws CloneNotSupportedException
   {
diff --git a/java/security/SignedObject.java b/java/security/SignedObject.java
index d565b2ea3..be5a67461 100644
--- a/java/security/SignedObject.java
+++ b/java/security/SignedObject.java
@@ -46,82 +46,34 @@ import java.io.ObjectOutputStream;
 import java.io.Serializable;
 
 /**
- * <p><code>SignedObject</code> is a class for the purpose of creating authentic
- * runtime objects whose integrity cannot be compromised without being detected.
- * </p>
- *
- * <p>More specifically, a <code>SignedObject</code> contains another
- * {@link Serializable} object, the (to-be-)signed object and its signature.</p>
- *
- * <p>The signed object is a <i>"deep copy"</i> (in serialized form) of an
- * original object. Once the copy is made, further manipulation of the original
- * object has no side effect on the copy.</p>
- *
- * <p>The underlying signing algorithm is designated by the {@link Signature}
- * object passed to the constructor and the <code>verify()</code> method. A
- * typical usage for signing is the following:</p>
- *
- * <pre>
- * Signature signingEngine = Signature.getInstance(algorithm, provider);
- * SignedObject so = new SignedObject(myobject, signingKey, signingEngine);
- * </pre>
- *
- * <p>A typical usage for verification is the following (having received
- * <code>SignedObject</code> so):</p>
- *
- * <pre>
- * Signature verificationEngine = Signature.getInstance(algorithm, provider);
- * if (so.verify(publickey, verificationEngine))
- *   try
- *     {
- *       Object myobj = so.getObject();
- *     }
- *   catch (ClassNotFoundException ignored) {};
- * </pre>
- *
- * <p>Several points are worth noting. First, there is no need to initialize the
- * signing or verification engine, as it will be re-initialized inside the
- * constructor and the <code>verify()</code> method. Secondly, for verification
- * to succeed, the specified public key must be the public key corresponding to
- * the private key used to generate the <code>SignedObject</code>.</p>
- *
- * <p>More importantly, for flexibility reasons, the <code>constructor</code>
- * and <code>verify()</code> method allow for customized signature engines,
- * which can implement signature algorithms that are not installed formally as
- * part of a crypto provider. However, it is crucial that the programmer writing
- * the verifier code be aware what {@link Signature} engine is being used, as
- * its own implementation of the <code>verify()</code> method is invoked to
- * verify a signature. In other words, a malicious {@link Signature} may choose
- * to always return <code>true</code> on verification in an attempt to bypass a
- * security check.</p>
- *
- * <p>The signature algorithm can be, among others, the NIST standard <i>DSS</i>,
- * using <i>DSA</i> and <i>SHA-1</i>. The algorithm is specified using the same
- * convention as that for signatures. The <i>DSA</i> algorithm using the
- * <i>SHA-1</i> message digest algorithm can be specified, for example, as
- * <code>"SHA/DSA"</code> or <code>"SHA-1/DSA"</code> (they are equivalent). In
- * the case of <i>RSA</i>, there are multiple choices for the message digest
- * algorithm, so the signing algorithm could be specified as, for example,
- * <code>"MD2/RSA"</code>, <code>"MD5/RSA"</code> or <code>"SHA-1/RSA"</code>.
- * The algorithm name must be specified, as there is no default.</p>
- *
- * <p>The name of the Cryptography Package Provider is designated also by the
- * {@link Signature} parameter to the <code>constructor</code> and the <code>
- * verify()</code> method. If the provider is not specified, the default
- * provider is used. Each installation can be configured to use a particular
- * provider as default.</p>
- *
- * <p>Potential applications of <code>SignedObject</code> include:</p>
- *
- * <ul>
- *  <li>It can be used internally to any Java runtime as an unforgeable
- *  authorization token -- one that can be passed around without the fear that
- *  the token can be maliciously modified without being detected.</li>
- *  <li>It can be used to sign and serialize data/object for storage outside the
- *  Java runtime (e.g., storing critical access control data on disk).</li>
- *  <li>Nested <i>SignedObjects</i> can be used to construct a logical sequence
- *  of signatures, resembling a chain of authorization and delegation.</li>
- * </ul>
+ * <code>SignedObject</code> is used for storing runtime objects whose
+ * integrity cannot be compromised without being detected.
+ * 
+ * <p><code>SignedObject</code> contains a {@link Serializable} object which is
+ * yet to be signed and a digital signature of that object.</p>
+ * 
+ * <p>The signed copy is a "deep copy" (in serialized form) of an original
+ * object. Any changes to that original instance are not reflected in the
+ * enclosed copy inside this <code>SignedObject</code>.</p>
+ * 
+ * <p>Several things to note are that, first there is no need to initialize the
+ * signature engine as this class will handle that automatically. Second,
+ * verification will only succeed if the public key corresponds to the private
+ * key used to generate the digital signature inside this
+ * <code>SignedObject</code>.</p>
+ * 
+ * <p>For fexibility, the signature engine can be specified in the constructor
+ * or the <code>verify()</code> method. Programmers wishing to verify
+ * <code>SignedObject</code>s should be aware of the {@link Signature} engine
+ * they use. A malicious or flawed {@link Signature} implementation may always
+ * return true on verification thus circumventing the intended secrity check
+ * provided by the <code>SignedObject</code>.</p>
+ * 
+ * <p>The GNU security provider offers an implementation of the standard NIST
+ * DSA which uses "DSA" and "SHA-1". It can be specified by "SHA/DSA",
+ * "SHA-1/DSA" or its OID. If the RSA signature algorithm is provided then it
+ * could be "MD2/RSA". "MD5/RSA", or "SHA-1/RSA". The algorithm must be
+ * specified because there is no default.</p>
  *
  * @author Mark Benvenuto (ivymccough@worldnet.att.net)
  * @since 1.2
@@ -139,16 +91,22 @@ public final class SignedObject implements Serializable
   private String thealgorithm;
 
   /**
-   * Constructs a <code>SignedObject</code> from any {@link Serializable}
-   * object. The given object is signed with the given signing key, using the
-   * designated signature engine.
-   *
-   * @param object the object to be signed.
-   * @param signingKey the private key for signing.
-   * @param signingEngine the signature signing engine.
-   * @throws IOException if an error occurs during serialization.
-   * @throws InvalidKeyException if the key is invalid.
-   * @throws SignatureException if signing fails.
+   * Constructs a new instance of <code>SignedObject</code> from a
+   * {@link Serializable} object. The object is signed with a designated
+   * private key and a signature engine.
+   * 
+   * @param object
+   *          the object to sign.
+   * @param signingKey
+   *          the key to use.
+   * @param signingEngine
+   *          the signature engine to use.
+   * @throws IOException
+   *           if a serialization error occurred.
+   * @throws InvalidKeyException
+   *           if the key is invalid.
+   * @throws SignatureException
+   *           if a signing error occurs.
    */
   public SignedObject(Serializable object, PrivateKey signingKey,
 		      Signature signingEngine)
@@ -170,12 +128,14 @@ public final class SignedObject implements Serializable
   }
 
   /**
-   * Retrieves the encapsulated object. The encapsulated object is de-serialized
-   * before it is returned.
-   *
+   * Returns the encapsulated object. The object is de-serialized before being
+   * returned.
+   * 
    * @return the encapsulated object.
-   * @throws IOException if an error occurs during de-serialization.
-   * @throws ClassNotFoundException if an error occurs during de-serialization.
+   * @throws IOException
+   *           if a de-serialization error occurs.
+   * @throws ClassNotFoundException
+   *           if the encapsulated object's class was not found.
    */
   public Object getObject() throws IOException, ClassNotFoundException
   {
@@ -189,9 +149,9 @@ public final class SignedObject implements Serializable
   }
 
   /**
-   * Retrieves the signature on the signed object, in the form of a byte array.
-   *
-   * @return a copy of the signature.
+   * Returns the signature bytes of the encapsulated object.
+   * 
+   * @return the signature bytes of the encapsulated object.
    */
   public byte[] getSignature()
   {
@@ -200,9 +160,9 @@ public final class SignedObject implements Serializable
   }
 
   /**
-   * Retrieves the name of the signature algorithm.
-   *
-   * @return the signature algorithm name.
+   * Returns the name of the signature algorithm.
+   * 
+   * @return the name of the signature algorithm.
    */
   public String getAlgorithm()
   {
@@ -210,16 +170,19 @@ public final class SignedObject implements Serializable
   }
 
   /**
-   * Verifies that the signature in this <code>SignedObject</code> is the valid
-   * signature for the object stored inside, with the given verification key,
-   * using the designated verification engine.
-   *
-   * @param verificationKey the public key for verification.
-   * @param verificationEngine the signature verification engine.
-   * @return <code>true</code> if the signature is valid, <code>false</code>
-   * otherwise.
-   * @throws SignatureException if signature verification failed.
-   * @throws InvalidKeyException if the verification key is invalid.
+   * Verifies the encapsulated digital signature by checking that it was
+   * generated by the owner of a designated public key.
+   * 
+   * @param verificationKey
+   *          the public key to use.
+   * @param verificationEngine
+   *          the signature engine to use.
+   * @return <code>true</code> if signature is correct, <code>false</code>
+   *         otherwise.
+   * @throws InvalidKeyException
+   *           if the key is invalid.
+   * @throws SignatureException
+   *           if verification fails.
    */
   public boolean verify(PublicKey verificationKey, Signature verificationEngine)
     throws InvalidKeyException, SignatureException
diff --git a/java/security/Signer.java b/java/security/Signer.java
index ae1463db8..c7780f6d3 100644
--- a/java/security/Signer.java
+++ b/java/security/Signer.java
@@ -38,35 +38,29 @@ exception statement from your version. */
 package java.security;
 
 /**
- * <p>This class is used to represent an {@link Identity} that can also
- * digitally sign data.</p>
- *
- * <p>The management of a signer's private keys is an important and sensitive
- * issue that should be handled by subclasses as appropriate to their intended
- * use.</p>
+ * <code>Signer</code> is a subclass of {@link Identity}. It is used to store a
+ * digital signature key with an <i>Identity</i>.
  *
  * @author Mark Benvenuto (ivymccough@worldnet.att.net)
- * @deprecated This class is no longer used. Its functionality has been replaced
- * by <code>java.security.KeyStore</code>, the <code>java.security.cert</code>
- * package, and <code>java.security.Principal</code>.
+ * @deprecated Replaced by <code>java.security.KeyStore</code>, the
+ * <code>java.security.cert</code> package, and <code>java.security.Principal</code>.
  */
 public abstract class Signer extends Identity
 {
   private static final long serialVersionUID = -1763464102261361480L;
   private PrivateKey privateKey = null;
 
-  /**
-   * Creates a <code>Signer</code>. This constructor should only be used for
-   * serialization.
-   */
+  /** Trivial constructor for serialization purposes. */
   protected Signer()
   {
   }
 
   /**
-   * Creates a <code>Signer</code> with the specified identity name.
-   *
-   * @param name the identity name.
+   * Constructs a new instance of <code>Signer</code> with the specified
+   * identity name.
+   * 
+   * @param name
+   *          the name of the identity to use.
    */
   public Signer(String name)
   {
@@ -74,12 +68,16 @@ public abstract class Signer extends Identity
   }
 
   /**
-   * Creates a <code>Signer</code> with the specified identity name and scope.
-   *
-   * @param name the identity name.
-   * @param scope the scope of the identity.
-   * @throws KeyManagementException if there is already an identity with the
-   * same name in the scope.
+   * Constructs a new instance of <code>Signer</code> with the specified
+   * identity name and {@link IdentityScope}.
+   * 
+   * @param name
+   *          the name of the the identity to use.
+   * @param scope
+   *          the {@link IdentityScope} to use.
+   * @throws KeyManagementException
+   *           if a duplicate identity <code>name</code> exists within
+   *           <code>scope</code>.
    */
   public Signer(String name, IdentityScope scope) throws KeyManagementException
   {
@@ -87,18 +85,12 @@ public abstract class Signer extends Identity
   }
 
   /**
-   * <p>Returns this signer's private key.</p>
-   *
-   * <p>First, if there is a security manager, its <code>checkSecurityAccess()
-   * </code> method is called with <code>"getSignerPrivateKey"</code> as its
-   * argument to see if it's ok to return the private key.</p>
-   *
-   * @return this signer's private key, or <code>null</code> if the private key
-   * has not yet been set.
-   * @throws SecurityException if a security manager exists and its
-   * <code>checkSecurityAccess()</code> method doesn't allow returning the
-   * private key.
-   * @see SecurityManager#checkSecurityAccess(String)
+   * Returns the private key of this <code>Signer</code>.
+   * 
+   * @returns the private key of this <code>Signer</code>.
+   * @throws SecurityException
+   *           if a {@link SecurityManager} is installed which disallows this
+   *           operation.
    */
   public PrivateKey getPrivateKey()
   {
@@ -110,20 +102,17 @@ public abstract class Signer extends Identity
   }
 
   /**
-   * <p>Sets the key pair (public key and private key) for this signer.</p>
-   *
-   * <p>First, if there is a security manager, its <code>checkSecurityAccess()
-   * </code> method is called with <code>"setSignerKeyPair"</code> as its
-   * argument to see if it's ok to set the key pair.</p>
-   *
-   * @param pair an initialized key pair.
-   * @throws InvalidParameterException if the key pair is not properly
-   * initialized.
-   * @throws KeyException if the key pair cannot be set for any other reason.
-   * @throws SecurityException if a security manager exists and its
-   * <code>checkSecurityAccess()</code> method doesn't allow setting the key
-   * pair.
-   * @see SecurityManager#checkSecurityAccess(String)
+   * Specifies the {@link KeyPair} associated with this <code>Signer</code>.
+   * 
+   * @param pair
+   *          the {@link KeyPair} to use.
+   * @throws InvalidParameterException
+   *           if the key-pair is invalid.
+   * @throws KeyException
+   *           if any another key-related error occurs.
+   * @throws SecurityException
+   *           if a {@link SecurityManager} is installed which disallows this
+   *           operation.
    */
   public final void setKeyPair(KeyPair pair)
     throws InvalidParameterException, KeyException
@@ -151,12 +140,7 @@ public abstract class Signer extends Identity
       throw new InvalidParameterException();
   }
 
-  /**
-   * Returns a string of information about the signer.
-   *
-   * @return a string of information about the signer.
-   * @see SecurityManager#checkSecurityAccess(String)
-   */
+  /** @returns a string representing this <code>Signer</code>. */
   public String toString()
   {
     return (getName() + ": " + privateKey);
diff --git a/java/security/interfaces/RSAMultiPrimePrivateCrtKey.java b/java/security/interfaces/RSAMultiPrimePrivateCrtKey.java
index d80b962d0..da7d7479d 100644
--- a/java/security/interfaces/RSAMultiPrimePrivateCrtKey.java
+++ b/java/security/interfaces/RSAMultiPrimePrivateCrtKey.java
@@ -54,6 +54,7 @@ public interface RSAMultiPrimePrivateCrtKey extends RSAPrivateKey
 {
   // Constants
   // --------------------------------------------------------------------------
+
   long serialVersionUID = 618058533534628008L;
 
   // Methods
@@ -67,45 +68,45 @@ public interface RSAMultiPrimePrivateCrtKey extends RSAPrivateKey
   BigInteger getPublicExponent();
 
   /**
-   * Returns the primeP.
+   * Returns the prime p.
    *
-   * @return the primeP.
+   * @return the prime p.
    */
   BigInteger getPrimeP();
 
   /**
-   * Returns the primeQ.
+   * Returns the prime q.
    *
-   * @return the primeQ.
+   * @return the prime q.
    */
   BigInteger getPrimeQ();
 
   /**
-   * Returns the primeExponentP.
+   * Returns the prime's exponent p.
    *
-   * @return the primeExponentP.
+   * @return the prime's exponent p.
    */
   BigInteger getPrimeExponentP();
 
   /**
-   * Returns the primeExponentQ.
+   * Returns the prime's exponent q.
    *
-   * @return the primeExponentQ.
+   * @return the prime's exponent q.
    */
   BigInteger getPrimeExponentQ();
 
   /**
-   * Returns the crtCoefficient.
+   * Returns the CRT Coefficient.
    *
-   * @return the crtCoefficient.
+   * @return the CRT Coefficient.
    */
   BigInteger getCrtCoefficient();
 
   /**
-   * Returns the otherPrimeInfo or <code>null</code> if there are only two
-   * prime factors (p and q).
+   * Returns the <i>OtherPrimeInfo</i> triplet MPIs or <code>null</code> if
+   * there are only two known prime factors (p and q).
    *
-   * @return the otherPrimeInfo.
+   * @return the <i>OtherPrimeInfo</i> INTEGERs.
    */
   RSAOtherPrimeInfo[] getOtherPrimeInfo();
 }
diff --git a/java/security/spec/PSSParameterSpec.java b/java/security/spec/PSSParameterSpec.java
index 7a14a24fb..f2a83d967 100644
--- a/java/security/spec/PSSParameterSpec.java
+++ b/java/security/spec/PSSParameterSpec.java
@@ -38,9 +38,9 @@ exception statement from your version. */
 package java.security.spec;
 
 /**
- * This class specifies a parameter spec for RSA PSS encoding scheme, as
- * defined in the PKCS#1 v2.1.
- *
+ * An implementation of {@link AlgorithmParameterSpec} for the RSA PSS encoding
+ * scheme.
+ * 
  * @since 1.4
  * @see AlgorithmParameterSpec
  * @see java.security.Signature
@@ -56,12 +56,13 @@ public class PSSParameterSpec implements AlgorithmParameterSpec
   // --------------------------------------------------------------------------
 
   /**
-   * Creates a new <code>PSSParameterSpec</code> given the salt length as
-   * defined in PKCS#1.
-   *
-   * @param saltLen the length of salt in bits to be used in PKCS#1 PSS encoding.
-   * @throws IllegalArgumentException if <code>saltLen</code> is less than
-   * <code>0</code>.
+   * Construct a new instance of <code>PSSParameterSpec</code> given a salt
+   * length.
+   * 
+   * @param saltLen
+   *          the length in bits of the salt.
+   * @throws IllegalArgumentException
+   *           if <code>saltLen</code> is less than <code>0</code>.
    */
   public PSSParameterSpec(int saltLen)
   {
@@ -78,11 +79,7 @@ public class PSSParameterSpec implements AlgorithmParameterSpec
   // Instance methods
   // --------------------------------------------------------------------------
 
-  /**
-   * Returns the salt length in bits.
-   *
-   * @return the salt length.
-   */
+  /** @return the length (in bits) of the salt. */
   public int getSaltLength()
   {
     return this.saltLen;
diff --git a/java/security/spec/RSAMultiPrimePrivateCrtKeySpec.java b/java/security/spec/RSAMultiPrimePrivateCrtKeySpec.java
index 519a02913..9e8ad0da7 100644
--- a/java/security/spec/RSAMultiPrimePrivateCrtKeySpec.java
+++ b/java/security/spec/RSAMultiPrimePrivateCrtKeySpec.java
@@ -40,9 +40,9 @@ package java.security.spec;
 import java.math.BigInteger;
 
 /**
- * This class specifies an RSA multi-prime private key, as defined in the
+ * This class represents an RSA multi-prime private key, as defined in the
  * PKCS#1 v2.1, using the <i>Chinese Remainder Theorem</i> (CRT) information
- * values for efficiency.
+ * values.
  *
  * @since 1.4
  * @see java.security.Key
@@ -70,29 +70,35 @@ public class RSAMultiPrimePrivateCrtKeySpec extends RSAPrivateKeySpec
   // --------------------------------------------------------------------------
 
   /**
-   * <p>Creates a new <code>RSAMultiPrimePrivateCrtKeySpec</code> given the
-   * modulus, publicExponent, privateExponent, primeP, primeQ, primeExponentP,
-   * primeExponentQ, crtCoefficient, and otherPrimeInfo as defined in PKCS#1
-   * v2.1.</p>
-   *
+   * Constructs a new instance of <code>RSAMultiPrimePrivateCrtKeySpec</code>
+   * given the various PKCS#1 v2.1 parameters.
+   * 
    * <p>Note that <code>otherPrimeInfo</code> is cloned when constructing this
    * object.</p>
-   *
-   * @param modulus the modulus n.
-   * @param publicExponent the public exponent e.
-   * @param privateExponent the private exponent d.
-   * @param primeP the prime factor p of n.
-   * @param primeQ the prime factor q of n.
-   * @param primeExponentP this is d mod (p-1).
-   * @param primeExponentQ this is d mod (q-1).
-   * @param crtCoefficient the Chinese Remainder Theorem coefficient q-1 mod p.
-   * @param otherPrimeInfo triplets of the rest of primes, <code>null</code>
-   * can be specified if there are only two prime factors (p and q).
-   * @throws NullPointerException if any of the parameters, i.e. modulus,
-   * publicExponent, privateExponent, primeP, primeQ, primeExponentP,
-   * primeExponentQ, crtCoefficient, is <code>null</code>.
-   * @throws IllegalArgumentException if an empty, i.e. 0-length,
-   * otherPrimeInfo is specified.
+   * 
+   * @param modulus
+   *          the modulus n.
+   * @param publicExponent
+   *          the public exponent e.
+   * @param privateExponent
+   *          the private exponent d.
+   * @param primeP
+   *          the prime factor p of n.
+   * @param primeQ
+   *          the prime factor q of n.
+   * @param primeExponentP
+   *          this is d mod (p-1).
+   * @param primeExponentQ
+   *          this is d mod (q-1).
+   * @param crtCoefficient
+   *          the Chinese Remainder Theorem coefficient q-1 mod p.
+   * @param otherPrimeInfo
+   *          triplets of the rest of primes, <code>null</code> can be
+   *          specified if there are only two prime factors (p and q).
+   * @throws NullPointerException
+   *           if any of the parameters is <code>null</code>.
+   * @throws IllegalArgumentException
+   *           if an empty <code>otherPrimeInfo</code> is specified.
    */
   public RSAMultiPrimePrivateCrtKeySpec(BigInteger modulus,
                                         BigInteger publicExponent,
@@ -153,9 +159,9 @@ public class RSAMultiPrimePrivateCrtKeySpec extends RSAPrivateKeySpec
   }
 
   /**
-   * Returns the primeP.
+   * Returns the prime p.
    *
-   * @return the primeP.
+   * @return the prime p.
    */
   public BigInteger getPrimeP()
   {
@@ -163,9 +169,9 @@ public class RSAMultiPrimePrivateCrtKeySpec extends RSAPrivateKeySpec
   }
 
   /**
-   * Returns the primeQ.
+   * Returns the prime q.
    *
-   * @return the primeQ.
+   * @return the prime q.
    */
   public BigInteger getPrimeQ()
   {
@@ -173,9 +179,9 @@ public class RSAMultiPrimePrivateCrtKeySpec extends RSAPrivateKeySpec
   }
 
   /**
-   * Returns the primeExponentP.
+   * Returns d mod (p-1).
    *
-   * @return the primeExponentP.
+   * @return d mod (p-1).
    */
   public BigInteger getPrimeExponentP()
   {
@@ -183,9 +189,9 @@ public class RSAMultiPrimePrivateCrtKeySpec extends RSAPrivateKeySpec
   }
 
   /**
-   * Returns the primeExponentQ.
+   * Returns d mod (q-1).
    *
-   * @return the primeExponentQ.
+   * @return d mod (q-1).
    */
   public BigInteger getPrimeExponentQ()
   {
@@ -193,9 +199,9 @@ public class RSAMultiPrimePrivateCrtKeySpec extends RSAPrivateKeySpec
   }
 
   /**
-   * Returns the crtCoefficient.
+   * Returns the CRT Coefficient q-1 mod p.
    *
-   * @return the crtCoefficient.
+   * @return the CRT Coefficient q-1 mod p.
    */
   public BigInteger getCrtCoefficient()
   {
@@ -203,10 +209,10 @@ public class RSAMultiPrimePrivateCrtKeySpec extends RSAPrivateKeySpec
   }
 
   /**
-   * Returns a copy of the otherPrimeInfo or <code>null</code> if there are
-   * only two prime factors (p and q).
+   * Returns a clone of <code>otherPrimeInfo</code> or <code>null</code> if
+   * it was <code>null</code> at construction time.
    *
-   * @return the otherPrimeInfo.
+   * @return a cloned copy of <code>otherPrimeInfo</code>.
    */
   public RSAOtherPrimeInfo[] getOtherPrimeInfo()
   {
diff --git a/java/security/spec/RSAOtherPrimeInfo.java b/java/security/spec/RSAOtherPrimeInfo.java
index 654bcb574..03cdca227 100644
--- a/java/security/spec/RSAOtherPrimeInfo.java
+++ b/java/security/spec/RSAOtherPrimeInfo.java
@@ -40,17 +40,8 @@ package java.security.spec;
 import java.math.BigInteger;
 
 /**
- * This class represents the triplet (prime, exponent, and coefficient) inside
- * RSA's OtherPrimeInfo structure, as defined in the PKCS#1 v2.1. The ASN.1
- * syntax of RSA's OtherPrimeInfo is as follows:
- *
- * <pre>
- *  OtherPrimeInfo ::= SEQUENCE {
- *    prime INTEGER,
- *    exponent INTEGER,
- *    coefficient INTEGER
- *  }
- * </pre>
+ * An in-memory representation of the RSA triplet (prime, exponent, and
+ * coefficient) inside a PKCS#1 v2.1 <i>OtherPrimeInfo</i> structure.
  *
  * @since 1.4
  * @see RSAPrivateCrtKeySpec
@@ -69,14 +60,16 @@ public class RSAOtherPrimeInfo
   // --------------------------------------------------------------------------
 
   /**
-   * Creates a new <code>RSAOtherPrimeInfo</code> given the prime,
-   * primeExponent, and crtCoefficient as defined in PKCS#1.
-   *
-   * @param prime the prime factor of n.
-   * @param primeExponent the exponent.
-   * @param crtCoefficient the Chinese Remainder Theorem coefficient.
-   * @throws NullPointerException if any of the parameters, i.e. prime,
-   * primeExponent, crtCoefficient, is <code>null</code>.
+   * Constructs a new <code>RSAOtherPrimeInfo</code> given the PKCS#1 MPIs.
+   * 
+   * @param prime
+   *          the prime factor of n.
+   * @param primeExponent
+   *          the exponent.
+   * @param crtCoefficient
+   *          the Chinese Remainder Theorem coefficient.
+   * @throws NullPointerException
+   *           if any of the parameters is <code>null</code>.
    */
   public RSAOtherPrimeInfo(BigInteger prime, BigInteger primeExponent,
                            BigInteger crtCoefficient)
@@ -122,9 +115,9 @@ public class RSAOtherPrimeInfo
   }
 
   /**
-   * Returns the prime's crtCoefficient.
+   * Returns the CRT Coefficient.
    *
-   * @return the crtCoefficient.
+   * @return the CRT Coefficient.
    */
   public final BigInteger getCrtCoefficient()
   {