fixes grammar issues in JavaDoc and code comments. (#233)

fixes some typos found along the way.
improves JavaDoc, highlighting the keywords: null, true, false.

PROPOSAL.html

@@ -55,7 +55,7 @@ <h3>(0) Rationale</h3>
 
 
 <p>Providing Java based optimized and high performance cryptographic IO streams for 
-the applications who wants to implement the data encryption. It also provides cipher 
+the applications that want to implement the data encryption. It also provides cipher
 level API to use. It does provide the openssl API integration and provide the fallback 
 mechanism to use JCE when openssl library unavailable.</p>
 
@@ -75,7 +75,7 @@ <h3>(1) Scope of the Package</h3>
 
 of OpenSSL library. </p>
 
-<p>It focuses on AES-NI optimizations mainly and it can be extended to other algorithms
+<p>It focuses on AES-NI optimizations mainly, and it can be extended to other algorithms
 
  based on demand from the users later.</p>
 

src/main/java/org/apache/commons/crypto/Crypto.java

@@ -89,7 +89,7 @@ private static Properties getComponentProperties() {
      * by Maven.
      * </p>
      *
-     * @return the version; may be null if not found
+     * @return the version; may be {@code null} if not found
      */
     public static String getComponentName() {
         // Note: the component properties file allows the method to work without needing
@@ -105,7 +105,7 @@ public static String getComponentName() {
      * by Maven.
      * </p>
      *
-     * @return the version; may be null if not found
+     * @return the version; may be {@code null} if not found
      */
     public static String getComponentVersion() {
         // Note: the component properties file allows the method to work without needing
@@ -116,7 +116,7 @@ public static String getComponentVersion() {
     /**
      * The loading error throwable, if loading failed.
      *
-     * @return null, unless loading failed.
+     * @return {@code null}, unless loading failed.
      */
     public static Throwable getLoadingError() {
         return NativeCodeLoader.getLoadingError();
@@ -137,7 +137,7 @@ private static void info(final String format, final Object... args) {
     /**
      * Checks whether the native code has been successfully loaded for the platform.
      *
-     * @return true if the native code has been loaded successfully.
+     * @return {@code true} if the native code has been loaded successfully.
      */
     public static boolean isNativeCodeLoaded() {
         return NativeCodeLoader.isNativeCodeLoaded();

src/main/java/org/apache/commons/crypto/NativeCodeLoader.java

@@ -68,10 +68,10 @@ final class NativeCodeLoader {
      * Copied from Apache Commons IO 2.5.
      * </p>
      *
-     * @param inputStream the InputStream to wrap or return (not null)
+     * @param inputStream the InputStream to wrap or return (not {@code null})
      * @return the given InputStream or a new {@link BufferedInputStream} for the
      *         given InputStream
-     * @throws NullPointerException if the input parameter is null
+     * @throws NullPointerException if the input parameter is {@code null}
      */
     @SuppressWarnings("resource")
     private static BufferedInputStream buffer(final InputStream inputStream) {
@@ -90,7 +90,7 @@ private static BufferedInputStream buffer(final InputStream inputStream) {
      *
      * @param input1 the input1.
      * @param input2 the input2.
-     * @return true if in1 and in2 is equal, else false.
+     * @return {@code true} if in1 and in2 is equal, else {@code false}.
      * @throws IOException if an I/O error occurs.
      */
     @SuppressWarnings("resource")

src/main/java/org/apache/commons/crypto/OpenSslInfoNative.java

@@ -38,7 +38,7 @@ final class OpenSslInfoNative {
     /**
      * Return the path to the loaded dynamic linked library.
      * [Currently not implemented on Windows]
-     * @return the path to the library that was loaded; may be null.
+     * @return the path to the library that was loaded; may be {@code null}.
      */
     public static native String DLLPath();
 

src/main/java/org/apache/commons/crypto/OsInfo.java

@@ -157,7 +157,7 @@ static String getOsNameProperty() {
     }
 
     /**
-     * The main method. This is used by the JNI make processing in Makefile.common
+     * The main method. This is used by the JNI make processing in {@code Makefile.common}
      *
      * @param args the argv.
      */

src/main/java/org/apache/commons/crypto/cipher/CryptoCipher.java

@@ -118,7 +118,7 @@ int doFinal(ByteBuffer inBuffer, ByteBuffer outBuffer)
      *         policy files).
      * @throws InvalidAlgorithmParameterException if the given algorithm
      *         parameters are inappropriate for this cipher, or this cipher
-     *         requires algorithm parameters and {@code params} is null, or
+     *         requires algorithm parameters and {@code params} is {@code null}, or
      *         the given algorithm parameters imply a cryptographic strength
      *         that would exceed the legal limits (as determined from the
      *         configured jurisdiction policy files).

src/main/java/org/apache/commons/crypto/cipher/JceCipher.java

@@ -152,7 +152,7 @@ public final int getBlockSize() {
      * @param params the algorithm parameters
      * @throws InvalidAlgorithmParameterException if the given algorithm
      *         parameters are inappropriate for this cipher, or this cipher
-     *         requires algorithm parameters and {@code params} is null, or
+     *         requires algorithm parameters and {@code params} is {@code null}, or
      *         the given algorithm parameters imply a cryptographic strength
      *         that would exceed the legal limits (as determined from the
      *         configured jurisdiction policy files).
@@ -218,7 +218,7 @@ public int update(final ByteBuffer inBuffer, final ByteBuffer outBuffer)
      * @param aad the buffer containing the Additional Authentication Data
      *
      * @throws IllegalArgumentException if the {@code aad}
-     * byte array is null
+     * byte array is {@code null}
      * @throws IllegalStateException if this cipher is in a wrong state
      * (e.g., has not been initialized), does not accept AAD, or if
      * operating in either GCM or CCM mode and one of the {@code update}
@@ -247,7 +247,7 @@ public void updateAAD(final byte[] aad) {
      * @param aad the buffer containing the Additional Authentication Data
      *
      * @throws IllegalArgumentException if the {@code aad}
-     * byte array is null
+     * byte array is {@code null}
      * @throws IllegalStateException if this cipher is in a wrong state
      * (e.g., has not been initialized), does not accept AAD, or if
      * operating in either GCM or CCM mode and one of the {@code update}

src/main/java/org/apache/commons/crypto/cipher/OpenSsl.java

@@ -86,7 +86,7 @@ static int get(final String algorithm, final String mode) throws NoSuchAlgorithm
      * @param transformation the name of the transformation, e.g.,
      *        AES/CTR/NoPadding.
      * @return OpenSslCipher an {@code OpenSslCipher} object
-     * @throws NoSuchAlgorithmException if {@code transformation} is null,
+     * @throws NoSuchAlgorithmException if {@code transformation} is {@code null},
      *         empty, in an invalid format, or if OpenSsl doesn't implement the
      *         specified algorithm.
      * @throws NoSuchPaddingException if {@code transformation} contains a
@@ -108,7 +108,7 @@ public static OpenSsl getInstance(final String transformation)
     /**
      * Gets the failure reason when loading OpenSsl native.
      *
-     * @return the failure reason; null if it was loaded and initialized successfully
+     * @return the failure reason; {@code null} if it was loaded and initialized successfully
      */
     public static Throwable getLoadingFailureReason() {
         return loadingFailureReason;

src/main/java/org/apache/commons/crypto/cipher/OpenSslCipher.java

@@ -224,7 +224,7 @@ public int update(final ByteBuffer inBuffer, final ByteBuffer outBuffer)
      * @param aad the buffer containing the Additional Authentication Data
      *
      * @throws IllegalArgumentException if the {@code aad}
-     * byte array is null
+     * byte array is {@code null}
      * @throws IllegalStateException if this opensslEngine is in a wrong state
      * (e.g., has not been initialized), does not accept AAD, or if
      * operating in either GCM mode and one of the {@code update}
@@ -264,7 +264,7 @@ public void updateAAD(final byte[] aad) throws IllegalArgumentException,
      * @param aad the buffer containing the Additional Authentication Data
      *
      * @throws IllegalArgumentException if the {@code aad}
-     * byte array is null
+     * byte array is {@code null}
      * @throws IllegalStateException if this opensslEngine is in a wrong state
      * (e.g., has not been initialized), does not accept AAD, or if
      * operating in either GCM mode and one of the {@code update}

src/main/java/org/apache/commons/crypto/cipher/OpenSslGaloisCounterMode.java

@@ -203,7 +203,7 @@ public int doFinal(final ByteBuffer input, final ByteBuffer output)
      * @param context The cipher context address
      * @param type CtrlValues
      * @param arg argument like a tag length
-     * @param data byte buffer or null
+     * @param data byte buffer or {@code null}
      * @return return 0 if there is any error, else return 1.
      */
     private int evpCipherCtxCtrl(final long context, final int type, final int arg, final ByteBuffer data) {

src/main/java/org/apache/commons/crypto/cipher/OpenSslNative.java

@@ -43,7 +43,7 @@ final class OpenSslNative {
      * @param context The cipher context address
      * @param type CtrlValues
      * @param arg argument like a tag length
-     * @param data byte buffer or null
+     * @param data byte buffer or {@code null}
      * @return return 0 if there is any error, else return 1.
      */
     public static native int ctrl(long context, int type, int arg, byte[] data);

src/main/java/org/apache/commons/crypto/jna/OpenSslJna.java

@@ -43,14 +43,14 @@ static void debug(final Object format, final Object... args) {
     }
 
     /**
-     * @return The cipher class of JNA implementation
+     * @return The cipher class of JNA implementation.
      */
     public static Class<? extends CryptoCipher> getCipherClass() {
         return OpenSslJnaCipher.class;
     }
 
     /**
-     * @return The random class of JNA implementation
+     * @return The random class of JNA implementation.
      */
     public static Class<? extends CryptoRandom> getRandomClass() {
         return OpenSslJnaCryptoRandom.class;
@@ -68,14 +68,14 @@ private static void info(final String format, final Object... args) {
     }
 
     /**
-     * @return the error of JNA
+     * @return the error of JNA.
      */
     public static Throwable initialisationError() {
         return OpenSslNativeJna.INIT_ERROR;
     }
 
     /**
-     * @return true if JNA native loads successfully
+     * @return {@code true} if JNA native loads successfully.
      */
     public static boolean isEnabled() {
         return OpenSslNativeJna.INIT_OK;

src/main/java/org/apache/commons/crypto/jna/OpenSslJnaCipher.java

@@ -325,7 +325,7 @@ public int update(final ByteBuffer inBuffer, final ByteBuffer outBuffer) throws
      *
      * @param aad the buffer containing the Additional Authentication Data
      *
-     * @throws IllegalArgumentException      if the {@code aad} byte array is null
+     * @throws IllegalArgumentException      if the {@code aad} byte array is {@code null}
      * @throws IllegalStateException         if this opensslEngine is in a wrong
      *                                       state (e.g., has not been initialized),
      *                                       does not accept AAD, or if operating in
@@ -355,7 +355,7 @@ public void updateAAD(final byte[] aad)
      *
      * @param aad the buffer containing the Additional Authentication Data
      *
-     * @throws IllegalArgumentException      if the {@code aad} byte array is null
+     * @throws IllegalArgumentException      if the {@code aad} byte array is {@code null}
      * @throws IllegalStateException         if this opensslEngine is in a wrong
      *                                       state (e.g., has not been initialized),
      *                                       does not accept AAD, or if operating in

src/main/java/org/apache/commons/crypto/jna/OpenSslJnaCryptoRandom.java

@@ -55,7 +55,7 @@ final class OpenSslJnaCryptoRandom implements CryptoRandom {
      * Constructs a {@link OpenSslJnaCryptoRandom}.
      *
      * @param props the configuration properties (not used)
-     * @throws GeneralSecurityException  if could not enable JNA access
+     * @throws GeneralSecurityException  if JNA access could not be enabled
      */
     public OpenSslJnaCryptoRandom(final Properties props) //NOPMD
             throws GeneralSecurityException {
@@ -105,7 +105,7 @@ public void close() {
 
     /**
      * Closes the rdrand engine.
-     * @param closing true when called while closing.
+     * @param closing {@code true} when called while closing.
      */
     private void closeRdrandEngine(final boolean closing) {
 
@@ -118,7 +118,7 @@ private void closeRdrandEngine(final boolean closing) {
     /**
      * Checks if rdrand engine is used to retrieve random bytes
      *
-     * @return true if rdrand is used, false if default engine is used
+     * @return {@code true} if rdrand is used, {@code false} if default engine is used
      */
     public boolean isRdrandEnabled() {
         return rdrandEnabled;
@@ -151,7 +151,7 @@ public void nextBytes(final byte[] bytes) {
 
     /**
      * @param retVal the result value of error.
-     * @param closing true when called while closing.
+     * @param closing {@code true} when called while closing.
      */
     private void throwOnError(final int retVal, final boolean closing) {
         if (retVal != 1) {

src/main/java/org/apache/commons/crypto/random/OpenSslCryptoRandom.java

@@ -83,7 +83,7 @@ private static void checkNative() throws GeneralSecurityException {
     /**
      * Judges whether native library was successfully loaded and initialized.
      *
-     * @return true if library was loaded and initialized
+     * @return {@code true} if library was loaded and initialized
      */
     public static boolean isNativeCodeEnabled() {
         return nativeEnabled;

src/main/java/org/apache/commons/crypto/random/OpenSslCryptoRandomNative.java

@@ -32,11 +32,11 @@ final class OpenSslCryptoRandomNative {
     public static native void initSR();
 
     /**
-     * Judges whether use {@link OpenSslCryptoRandomNative} to generate the
+     * Judges whether to use {@link OpenSslCryptoRandomNative} to generate the
      * user-specified number of random bits.
      *
      * @param bytes the array to be filled in with random bytes.
-     * @return true if use {@link OpenSslCryptoRandomNative} to generate the
+     * @return {@code true} if use {@link OpenSslCryptoRandomNative} to generate the
      *         user-specified number of random bits.
      */
     public static native boolean nextRandBytes(byte[] bytes);

src/main/java/org/apache/commons/crypto/stream/CryptoInputStream.java

@@ -493,7 +493,7 @@ public boolean isOpen() {
     /**
      * Overrides the {@link InputStream#markSupported()}.
      *
-     * @return false, the {@link CtrCryptoInputStream} don't support the mark
+     * @return {@code false} if the {@link CtrCryptoInputStream} don't support the mark
      *         method.
      */
     @Override

src/main/java/org/apache/commons/crypto/stream/CtrCryptoInputStream.java

@@ -487,7 +487,7 @@ protected void initCipher() {
      * This method is executed immediately after decryption. Checks whether
      * cipher should be updated and recalculate padding if needed.
      *
-     * @param position the given position in the data..
+     * @param position the given position in the data.
      * @return the byte.
      * @throws IOException if an I/O error occurs.
      */

src/main/java/org/apache/commons/crypto/stream/input/Input.java

@@ -28,7 +28,7 @@
 /**
  * The Input interface abstract the input source of
  * {@link CryptoInputStream} so that different implementation of input can
- * be used. The implementation Input interface will usually wraps an input
+ * be used. The implementation Input interface will usually wrap an input
  * mechanism such as {@link InputStream} or
  * {@link ReadableByteChannel}.
  */

src/main/java/org/apache/commons/crypto/stream/output/Output.java

@@ -28,7 +28,7 @@
 /**
  * The Output interface abstract the output target of
  * {@link CryptoOutputStream} so that different implementation of output
- * can be used. The implementation Output interface will usually wraps an output
+ * can be used. The implementation Output interface will usually wrap an output
  * mechanism such as {@link OutputStream} or
  * {@link WritableByteChannel}.
  */

src/main/java/org/apache/commons/crypto/utils/ReflectionUtils.java

@@ -69,11 +69,11 @@ public static Class<?> getClassByName(final String name) throws ClassNotFoundExc
     }
 
     /**
-     * Loads a class by name, returning null rather than throwing an exception if it
+     * Loads a class by name, returning {@code null} rather than throwing an exception if it
      * couldn't be loaded. This is to avoid the overhead of creating an exception.
      *
      * @param name the class name.
-     * @return the class object, or null if it could not be found.
+     * @return the class object, or {@code null} if it could not be found.
      */
     private static Class<?> getClassByNameOrNull(final String name) {
         final Map<String, WeakReference<Class<?>>> map;