Fix 157622: cleanup javadoc warnings.

These changes should only affect documentation. There should be no
functional effect of the changes.

security/jss/build_java.pl

@@ -68,7 +68,6 @@ org.mozilla.jss.pkix.cmc
 org.mozilla.jss.pkix.cmmf
 org.mozilla.jss.pkix.cms
 org.mozilla.jss.pkix.crmf
-org.mozilla.jss.provider
 org.mozilla.jss.provider.java.security
 org.mozilla.jss.provider.javax.crypto
 org.mozilla.jss.ssl
@@ -282,6 +281,6 @@ sub javadoc {
     ensure_dir_exists("$dist_dir/jssdoc");
     my $targets = join(" ", @packages);
     print "$targets\n";
-    print_do("$javadoc -private -sourcepath . -d $dist_dir/jssdoc $html_header_opt $targets");
+    print_do("$javadoc -private -breakiterator -sourcepath . -d $dist_dir/jssdoc $html_header_opt $targets");
     #print "$javadoc -private -sourcepath . -d $dist_dir/jssdoc $html_header_opt $targets" . "\n";
 }

security/jss/org/mozilla/jss/crypto/KeyWrapper.java

@@ -81,7 +81,7 @@ public interface KeyWrapper {
      * A permanent private key object resides on a token until it is
      * explicitly deleted from the token.
      *
-     * @publicKey Used to calculate the key identifier that must be stored
+     * @param publicKey Used to calculate the key identifier that must be stored
      *  with the private key. Must be a <code>RSAPublicKey</code> or a
      *  <code>DSAPublicKey</code>.
      * @exception InvalidKeyException If the type of the public key does not
@@ -97,7 +97,7 @@ public interface KeyWrapper {
      * private key is one that does not permanently reside on a token.
      * As soon as it is garbage-collected, it is gone forever.
      *
-     * @publicKey Used to calculate the key identifier that must be stored
+     * @param publicKey Used to calculate the key identifier that must be stored
      *  with the private key. Must be a <code>RSAPublicKey</code> or a
      *  <code>DSAPublicKey</code>.
      * @exception InvalidKeyException If the type of the public key does not

security/jss/org/mozilla/jss/crypto/X509Certificate.java

@@ -76,7 +76,7 @@ public interface X509Certificate
     getSerialNumber();
 
     /**
-     * Returns the version number of this X.509 certificate.
+     * @return the version number of this X.509 certificate.
      * 0 means v1, 1 means v2, 2 means v3.
      */
     public abstract int

security/jss/org/mozilla/jss/pkcs11/PK11SecureRandom.java

@@ -49,20 +49,6 @@ class PK11SecureRandom implements org.mozilla.jss.crypto.JSSSecureRandom
     // construction and finalization
     ////////////////////////////////////////////////////
 
-    /**
-     *  While it would be "nice" to add the following code
-     *  snippet to check initialization of the random
-     *  number generator prior to using any of the functions,
-     *  a circular link dependency prevents this:
-     *
-     *      try {
-     *        CryptoManager.getInstance();
-     *      }
-     *      catch ( CryptoManager.NotInitializedException e ) {
-     *        Assert.notReached("Pseudorandom number generator " +
-     *                          "has not been initialized!" );
-     *      }
-     */
     public
     PK11SecureRandom() {}
 

security/jss/org/mozilla/jss/pkcs11/PK11Signature.java

@@ -43,9 +43,6 @@ import org.mozilla.jss.crypto.PrivateKey;
 
 final class PK11Signature extends org.mozilla.jss.crypto.SignatureSpi {
 
-    /*************************************************************
-    ** PK11Signature
-    */
 	public PK11Signature(PK11Token token, SignatureAlgorithm algorithm)
 		throws NoSuchAlgorithmException, TokenException
 	{
@@ -70,9 +67,6 @@ final class PK11Signature extends org.mozilla.jss.crypto.SignatureSpi {
 		this.state = UNINITIALIZED;
 	}
 
-    /*************************************************************
-    ** engineInitSign
-    */
 	public void engineInitSign(org.mozilla.jss.crypto.PrivateKey privateKey)
 		throws InvalidKeyException, TokenException
 	{
@@ -128,9 +122,7 @@ final class PK11Signature extends org.mozilla.jss.crypto.SignatureSpi {
 	}
 
     /*************************************************************
-    ** engineInitSign
-    **
-    ** This just here for JCA compliance(?), we don't take randoms this way.
+    ** This is just here for JCA compliance, we don't take randoms this way.
     */
 	public void
     engineInitSign(org.mozilla.jss.crypto.PrivateKey privateKey,
@@ -143,18 +135,13 @@ final class PK11Signature extends org.mozilla.jss.crypto.SignatureSpi {
 	}
 
     /*************************************************************
-    ** initSigContext
-    **
-    ** This function creates a signing context, initializes it,
+    ** Creates a signing context, initializes it,
     ** and sets the sigContext field.
     */
     protected native void initSigContext()
         throws TokenException;
 
 
-    /*************************************************************
-    ** engineInitVerify
-    */
 	public void engineInitVerify(PublicKey publicKey)
 		throws InvalidKeyException, TokenException
 	{
@@ -203,23 +190,14 @@ final class PK11Signature extends org.mozilla.jss.crypto.SignatureSpi {
 		state = VERIFY;
 	}
 
-    /*************************************************************
-    ** initVfyContext
-    */
     protected native void initVfyContext() throws TokenException;
 
-    /*************************************************************
-    ** engineUpdate
-    */
 	public void engineUpdate(byte b)
         throws SignatureException, TokenException
     {
         engineUpdate(new byte[] {b}, 0, 1);
     }
 
-    /*************************************************************
-    ** engineUpdate
-    */
     public void engineUpdate(byte[] b, int off, int len)
         throws SignatureException, TokenException
     {
@@ -249,16 +227,10 @@ final class PK11Signature extends org.mozilla.jss.crypto.SignatureSpi {
         }
     }
 
-    /*************************************************************
-    ** engineUpdateNative
-    */
     protected native void engineUpdateNative(byte[] b, int off, int len)
         throws TokenException;
     
 
-    /*************************************************************
-    ** engineSign
-    */
     public byte[] engineSign()
         throws SignatureException, TokenException
     {
@@ -289,9 +261,6 @@ final class PK11Signature extends org.mozilla.jss.crypto.SignatureSpi {
 		return result;
     }
 
-    /*************************************************************
-    ** engineSign
-    */
     public int engineSign(byte[] outbuf, int offset, int len)
         throws SignatureException, TokenException
     {
@@ -321,15 +290,9 @@ final class PK11Signature extends org.mozilla.jss.crypto.SignatureSpi {
         PrivateKey key, byte[] hash)
         throws SignatureException, TokenException;
 
-    /*************************************************************
-    ** engineSignNative
-    */
     private native byte[] engineSignNative()
         throws SignatureException, TokenException;
 
-    /*************************************************************
-    ** engineVerify
-    */
     public boolean engineVerify(byte[] sigBytes)
         throws SignatureException, TokenException
     {
@@ -377,15 +340,9 @@ final class PK11Signature extends org.mozilla.jss.crypto.SignatureSpi {
         PublicKey key, byte[] hash, byte[] signature)
         throws SignatureException, TokenException;
 
-	/**********************************************************************
-	** engineVerifyNative
-	*/
 	native protected boolean engineVerifyNative(byte[] sigBytes)
 		throws SignatureException, TokenException;
 
-    /*************************************************************
-    ** engineSetParameter
-    */
     public void engineSetParameter(AlgorithmParameterSpec params)
         throws InvalidAlgorithmParameterException, TokenException
     {

security/jss/org/mozilla/jss/pkcs11/PK11Token.java

@@ -45,7 +45,7 @@ import java.security.InvalidParameterException;
  * CryptoManager class.
  *
  * @author nicolson
- * @version $Revision: 1.4 $ $Date: 2002/05/02 04:03:49 $ 
+ * @version $Revision: 1.5 $ $Date: 2002/07/15 22:47:53 $ 
  * @see org.mozilla.jss.CryptoManager
  */
 public final class PK11Token implements CryptoToken {
@@ -449,7 +449,7 @@ public final class PK11Token implements CryptoToken {
      * @param P The DSA prime parameter
      * @param Q The DSA sub-prime parameter
      * @param G The DSA base parameter
-	 * @ return String that represents a PKCS#10 b64 encoded blob with
+	 * @return String that represents a PKCS#10 b64 encoded blob with
 	 * begin/end brackets
 	 */
 	public String generateCertRequest(String subject, int keysize,

security/jss/org/mozilla/jss/pkix/crmf/CertReqMsg.java

@@ -221,7 +221,7 @@ public class CertReqMsg implements ASN1Value {
          *
          * @return A new <i>CertReqMsg</i>.  The return value may be cast
          *      to a <code>CertReqMsg</code>.
-         * @throw InvalidBERException If the data on the input stream is not
+         * @throws InvalidBERException If the data on the input stream is not
          *      a valid BER encoding of a <i>CertReqMsg</i>.
          */
         public ASN1Value decode(InputStream istream)
@@ -239,7 +239,7 @@ public class CertReqMsg implements ASN1Value {
          *      where it is implicitly tagged.
          * @return A new <i>CertReqMsg</i>.  The return value may be cast
          *      to a <code>CertReqMsg</code>.
-         * @throw InvalidBERException If the data on the input stream is not
+         * @throws InvalidBERException If the data on the input stream is not
          *      a valid BER encoding of a <i>CertReqMsg</i>.
          */
         public ASN1Value decode(Tag implicit, InputStream istream)

security/jss/org/mozilla/jss/pkix/primitive/Name.java

@@ -158,7 +158,7 @@ public class Name implements ASN1Value {
 
     /**
      * Adds a common name (CN) to the Name.
-     * @CN The common name.
+     * @param CN The common name.
      *      It will be formatted according to the IETF PKIX rules for
      *      directory strings.
      */
@@ -168,7 +168,7 @@ public class Name implements ASN1Value {
 
     /**
      * Adds a country name (C) to the Name. It must be exactly two characters.
-     * @C The country name.
+     * @param C The country name.
      *      It will be formatted according to the IETF PKIX rules for
      *      directory strings.
      * @exception IllegalArgumentException If C.length() != 2.
@@ -183,7 +183,7 @@ public class Name implements ASN1Value {
 
     /**
      * Adds a locality name (L) to the Name.
-     * @L The locality name.
+     * @param L The locality name.
      *      It will be formatted according to the IETF PKIX rules for
      *      directory strings.
      */
@@ -193,7 +193,7 @@ public class Name implements ASN1Value {
 
     /**
      * Adds a state or province name (S) to the Name.
-     * @S The state or province name.
+     * @param S The state or province name.
      *      It will be formatted according to the IETF PKIX rules for
      *      directory strings.
      */
@@ -205,7 +205,7 @@ public class Name implements ASN1Value {
 
     /**
      * Adds an organization name (O) to the Name.
-     * @O The organization name.
+     * @param O The organization name.
      *      It will be formatted according to the IETF PKIX rules for
      *      directory strings.
      */
@@ -215,7 +215,7 @@ public class Name implements ASN1Value {
 
     /**
      * Adds an organizational unit name (OU) to the Name.
-     * @OU The organizational unit name.
+     * @param OU The organizational unit name.
      *      It will be formatted according to the IETF PKIX rules for
      *      directory strings.
      */

security/jss/org/mozilla/jss/ssl/SSLServerSocket.java

@@ -307,7 +307,7 @@ public class SSLServerSocket extends java.net.ServerSocket {
     }
 
     /**
-     * @Return the local address of this server socket.
+     * @return the local address of this server socket.
      */
     public InetAddress getInetAddress() {
         return base.getLocalAddress();

security/jss/org/mozilla/jss/ssl/SocketBase.java

@@ -167,7 +167,7 @@ class SocketBase {
     }
 
     /**
-     * @Return the InetAddress of the peer end of the socket.
+     * @return the InetAddress of the peer end of the socket.
      */
     InetAddress getInetAddress()
     {

security/jss/org/mozilla/jss/util/Password.java

@@ -79,7 +79,7 @@ public class Password implements PasswordCallback, Cloneable,
      * <code>PasswordCallback</code>.  This method simply returns a clone
      * of the password.
      *
-     * @returns A copy of the password.  The caller is responsible for
+     * @return A copy of the password.  The caller is responsible for
      *  clearing this copy.
      */
     public synchronized Password
@@ -205,7 +205,7 @@ public class Password implements PasswordCallback, Cloneable,
 	 *
 	 * @param charArray A character array, which should not be null. It will
 	 *		be wiped with zeroes.
-	 * @returns A copy of the charArray, converted from Unicode to UTF8. It
+	 * @return A copy of the charArray, converted from Unicode to UTF8. It
 	 * 	is the responsibility of the caller to clear the output byte array;
 	 *	<code>wipeBytes</code> is ideal for this purpose.
 	 * @see Password#wipeBytes

security/jss/org/mozilla/jss/util/PasswordCallback.java

@@ -75,7 +75,7 @@ public interface PasswordCallback {
      * throwing a <code>GiveUpException</code>.
      *
 	 * @param info Information about the token that is being logged into.
-	 * @returns The password.  This password object is owned by and will
+	 * @return The password.  This password object is owned by and will
      *      be cleared by the caller.
      * @exception GiveUpException If the callback does not want to supply
      *  a password.  This may often be the case if the first attempt failed.