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.

1 files changed, 77 insertions, 120 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();