This is an automated email from the ASF dual-hosted git repository.
ggregory pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-codec.git
The following commit(s) were added to refs/heads/master by this push:
new 14068c64 Javadoc
14068c64 is described below
commit 14068c64dc7c2114d6f8130d0aabf187edcba1d0
Author: Gary Gregory <[email protected]>
AuthorDate: Sun Jun 4 08:58:15 2023 -0400
Javadoc
Close HTML tags
Fix Javadoc formatting
---
.../org/apache/commons/codec/digest/Crypt.java | 12 ++++++--
.../apache/commons/codec/digest/DigestUtils.java | 2 ++
.../commons/codec/digest/HmacAlgorithms.java | 2 +-
.../org/apache/commons/codec/digest/HmacUtils.java | 32 ++++++++++------------
.../org/apache/commons/codec/digest/Md5Crypt.java | 5 ++--
.../apache/commons/codec/digest/MurmurHash2.java | 2 ++
.../apache/commons/codec/digest/MurmurHash3.java | 10 ++++---
.../apache/commons/codec/digest/PureJavaCrc32.java | 14 ++++++----
.../commons/codec/digest/PureJavaCrc32C.java | 10 +++++--
.../org/apache/commons/codec/digest/Sha2Crypt.java | 5 ++++
.../org/apache/commons/codec/digest/UnixCrypt.java | 4 +++
.../org/apache/commons/codec/digest/XXHash32.java | 1 +
12 files changed, 64 insertions(+), 35 deletions(-)
diff --git a/src/main/java/org/apache/commons/codec/digest/Crypt.java
b/src/main/java/org/apache/commons/codec/digest/Crypt.java
index f6ac066c..529c13b8 100644
--- a/src/main/java/org/apache/commons/codec/digest/Crypt.java
+++ b/src/main/java/org/apache/commons/codec/digest/Crypt.java
@@ -24,8 +24,10 @@ import java.util.concurrent.ThreadLocalRandom;
* GNU libc crypt(3) compatible hash method.
* <p>
* See {@link #crypt(String, String)} for further details.
+ * </p>
* <p>
* This class is immutable and thread-safe.
+ * </p>
*
* @since 1.7
*/
@@ -57,6 +59,7 @@ public class Crypt {
* <p>
* If no salt is provided, a random salt and the default algorithm
(currently SHA-512) will be used. See
* {@link #crypt(String, String)} for details.
+ * </p>
*
* @param keyBytes
* plaintext password
@@ -112,6 +115,7 @@ public class Crypt {
* Encrypts a password in a crypt(3) compatible way.
* <p>
* The exact algorithm depends on the format of the salt string:
+ * </p>
* <ul>
* <li>SHA-512 salts start with {@code $6$} and are up to 16 chars long.
* <li>SHA-256 salts start with {@code $5$} and are up to 16 chars long
@@ -119,13 +123,15 @@ public class Crypt {
* <li>DES, the traditional UnixCrypt algorithm is used with only 2 chars
* <li>Only the first 8 chars of the passwords are used in the DES
algorithm!
* </ul>
+ * <p>
* The magic strings {@code "$apr1$"} and {@code "$2a$"} are not
recognized by this method as its output should be
* identical with that of the libc implementation.
+ * </p>
* <p>
* The rest of the salt string is drawn from the set {@code [a-zA-Z0-9./]}
and is cut at the maximum length of if a
* {@code "$"} sign is encountered. It is therefore valid to enter a
complete hash value as salt to e.g. verify a
* password with:
- *
+ * </p>
* <pre>
* storedPwd.equals(crypt(enteredPwd, storedPwd))
* </pre>
@@ -135,6 +141,7 @@ public class Crypt {
* This is followed by the actual hash value.
* For DES the string only contains the salt and actual hash.
* The total length is dependent on the algorithm used:
+ * </p>
* <ul>
* <li>SHA-512: 106 chars
* <li>SHA-256: 63 chars
@@ -143,7 +150,7 @@ public class Crypt {
* </ul>
* <p>
* Example:
- *
+ * </p>
* <pre>
* crypt("secret", "$1$xxxx") => "$1$xxxx$aMkevjfEIpa35Bh3G4bAc."
* crypt("secret", "xx") => "xxWAum7tHdIUw"
@@ -151,6 +158,7 @@ public class Crypt {
* <p>
* This method comes in a variation that accepts a byte[] array to support
input strings that are not encoded in
* UTF-8 but e.g. in ISO-8859-1 where equal characters result in different
byte values.
+ * </p>
*
* @see "The man page of the libc crypt (3) function."
* @param key
diff --git a/src/main/java/org/apache/commons/codec/digest/DigestUtils.java
b/src/main/java/org/apache/commons/codec/digest/DigestUtils.java
index fd6294f0..bf851d70 100644
--- a/src/main/java/org/apache/commons/codec/digest/DigestUtils.java
+++ b/src/main/java/org/apache/commons/codec/digest/DigestUtils.java
@@ -42,10 +42,12 @@ import org.apache.commons.codec.binary.StringUtils;
* The {@link MessageDigestAlgorithms} class provides constants for standard
* digest algorithms that can be used with the {@link #getDigest(String)}
method
* and other methods that require the Digest algorithm name.
+ * </p>
* <p>
* Note: the class has shorthand methods for all the algorithms present as
standard in Java 6.
* This approach requires lots of methods for each algorithm, and quickly
becomes unwieldy.
* The following code works with all algorithms:
+ * </p>
* <pre>
* import static
org.apache.commons.codec.digest.MessageDigestAlgorithms.SHA_224;
* ...
diff --git a/src/main/java/org/apache/commons/codec/digest/HmacAlgorithms.java
b/src/main/java/org/apache/commons/codec/digest/HmacAlgorithms.java
index 76f83a7c..c58dc3bc 100644
--- a/src/main/java/org/apache/commons/codec/digest/HmacAlgorithms.java
+++ b/src/main/java/org/apache/commons/codec/digest/HmacAlgorithms.java
@@ -104,7 +104,7 @@ public enum HmacAlgorithms {
}
/**
- * The algorithm name
+ * The algorithm name.
*
* @see <a
href="http://docs.oracle.com/javase/6/docs/technotes/guides/security/SunProviders.html#SunJCEProvider";>
* Java 6 Cryptography Architecture Sun Providers Documentation</a>
diff --git a/src/main/java/org/apache/commons/codec/digest/HmacUtils.java
b/src/main/java/org/apache/commons/codec/digest/HmacUtils.java
index 00700ddb..9b76bd77 100644
--- a/src/main/java/org/apache/commons/codec/digest/HmacUtils.java
+++ b/src/main/java/org/apache/commons/codec/digest/HmacUtils.java
@@ -39,8 +39,10 @@ import org.apache.commons.codec.binary.StringUtils;
* <p>
* <strong>Note: Not all JCE implementations support all algorithms. If not
supported, an IllegalArgumentException is
* thrown.</strong>
+ * </p>
* <p>
* Sample usage:
+ * </p>
* <pre>
* import static HmacAlgorithms.*;
* byte[] key = {1,2,3,4}; // don't use this actual key!
@@ -58,12 +60,12 @@ public final class HmacUtils {
private static final int STREAM_BUFFER_LENGTH = 1024;
/**
- * Returns whether this algorithm is available
- *
- *@param name the name to check
- * @return whether this algorithm is available
- * @since 1.11
- */
+ * Returns whether this algorithm is available
+ *
+ * @param name the name to check
+ * @return whether this algorithm is available
+ * @since 1.11
+ */
public static boolean isAvailable(final String name) {
try {
Mac.getInstance(name);
@@ -74,12 +76,12 @@ public final class HmacUtils {
}
/**
- * Returns whether this algorithm is available
- *
- *@param name the name to check
- * @return whether this algorithm is available
- * @since 1.11
- */
+ * Returns whether this algorithm is available
+ *
+ * @param name the name to check
+ * @return whether this algorithm is available
+ * @since 1.11
+ */
public static boolean isAvailable(final HmacAlgorithms name) {
try {
Mac.getInstance(name.getName());
@@ -241,8 +243,6 @@ public final class HmacUtils {
}
}
- // hmacMd5
-
/**
* Returns a HmacMD5 Message Authentication Code (MAC) for the given key
and value.
*
@@ -469,8 +469,6 @@ public final class HmacUtils {
return new HmacUtils(HmacAlgorithms.HMAC_SHA_1,
key).hmacHex(valueToDigest);
}
- // hmacSha256
-
/**
* Returns a HmacSHA256 Message Authentication Code (MAC) for the given
key and value.
*
@@ -811,8 +809,6 @@ public final class HmacUtils {
return new HmacUtils(HmacAlgorithms.HMAC_SHA_512,
key).hmacHex(valueToDigest);
}
- // update
-
/**
* Resets and then updates the given {@link Mac} with the value.
*
diff --git a/src/main/java/org/apache/commons/codec/digest/Md5Crypt.java
b/src/main/java/org/apache/commons/codec/digest/Md5Crypt.java
index 0fbe3b38..de65e34c 100644
--- a/src/main/java/org/apache/commons/codec/digest/Md5Crypt.java
+++ b/src/main/java/org/apache/commons/codec/digest/Md5Crypt.java
@@ -147,6 +147,7 @@ public class Md5Crypt {
* <p>
* The algorithm is identical to the crypt(3) "$1$" one but produces
different outputs due to the different salt
* prefix.
+ * </p>
*
* @param keyBytes
* plaintext string to hash.
@@ -168,7 +169,7 @@ public class Md5Crypt {
* Generates a libc6 crypt() compatible "$1$" hash value.
* <p>
* See {@link #md5Crypt(byte[], String)} for details.
- *</p>
+ * </p>
* <p>
* A salt is generated for you using {@link ThreadLocalRandom}; for more
secure salts consider using
* {@link SecureRandom} to generate your own salts and calling {@link
#md5Crypt(byte[], String)}.
@@ -188,7 +189,7 @@ public class Md5Crypt {
* Generates a libc6 crypt() compatible "$1$" hash value.
* <p>
* See {@link #md5Crypt(byte[], String)} for details.
- *</p>
+ * </p>
* <p>
* A salt is generated for you using the instance of {@link Random} you
supply.
* </p>
diff --git a/src/main/java/org/apache/commons/codec/digest/MurmurHash2.java
b/src/main/java/org/apache/commons/codec/digest/MurmurHash2.java
index 8fefbe33..fbecba00 100644
--- a/src/main/java/org/apache/commons/codec/digest/MurmurHash2.java
+++ b/src/main/java/org/apache/commons/codec/digest/MurmurHash2.java
@@ -247,7 +247,9 @@ public final class MurmurHash2 {
* Before 1.14 the string was converted using default encoding.
* Since 1.14 the string is converted to bytes using UTF-8 encoding.
* </p>
+ * <p>
* This is a helper method that will produce the same result as:
+ * </p>
*
* <pre>
* int seed = 0xe17a1465;
diff --git a/src/main/java/org/apache/commons/codec/digest/MurmurHash3.java
b/src/main/java/org/apache/commons/codec/digest/MurmurHash3.java
index b46c6ff5..2291c512 100644
--- a/src/main/java/org/apache/commons/codec/digest/MurmurHash3.java
+++ b/src/main/java/org/apache/commons/codec/digest/MurmurHash3.java
@@ -647,9 +647,9 @@ public final class MurmurHash3 {
*/
@Deprecated
public static long hash64(final byte[] data, final int offset, final int
length, final int seed) {
- // ************
+ //
// Note: This fails to apply masking using 0xffffffffL to the seed.
- // ************
+ //
long hash = seed;
final int nblocks = length >> 3;
@@ -743,7 +743,9 @@ public final class MurmurHash3 {
* Before 1.14 the string was converted using default encoding.
* Since 1.14 the string is converted to bytes using UTF-8 encoding.
* </p>
+ * <p>
* This is a helper method that will produce the same result as:
+ * </p>
*
* <pre>
* int offset = 0;
@@ -1112,7 +1114,7 @@ public final class MurmurHash3 {
}
/**
- * Generate the 32-bit hash value. Repeat calls to this method with no
additional data
+ * Generates the 32-bit hash value. Repeat calls to this method with
no additional data
* will generate the same hash value.
*
* @return The 32-bit hash
@@ -1123,7 +1125,7 @@ public final class MurmurHash3 {
}
/**
- * Finalize the running hash to the output 32-bit hash by processing
remaining bytes
+ * Finalizes the running hash to the output 32-bit hash by processing
remaining bytes
* and performing final mixing.
*
* @param hash The running hash
diff --git a/src/main/java/org/apache/commons/codec/digest/PureJavaCrc32.java
b/src/main/java/org/apache/commons/codec/digest/PureJavaCrc32.java
index da051fca..0b52dd16 100644
--- a/src/main/java/org/apache/commons/codec/digest/PureJavaCrc32.java
+++ b/src/main/java/org/apache/commons/codec/digest/PureJavaCrc32.java
@@ -21,20 +21,24 @@ import java.util.zip.Checksum;
/**
* A pure-java implementation of the CRC32 checksum that uses
* the same polynomial as the built-in native CRC32.
- *
+ * <p>
* This is to avoid the JNI overhead for certain uses of checksumming
* where many small pieces of data are checksummed in succession.
- *
+ * </p>
+ * <p>
* The current version is ~10x to 1.8x as fast as Sun's native
* java.util.zip.CRC32 in Java 1.6
- *
- * Copied from Hadoop 2.6.3.
+ * </p>
+ * <p>
+ * Copied from Apache Hadoop 2.6.3.
* The code agrees with the following file in the 2.6.3 tag:
* https://gitbox.apache.org/repos/asf?p=hadoop.git;a=blob_plain;
*
f=hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/util/PureJavaCrc32.java;
* hb=2120de588b92b9f22b1cc4188761d6a8c61aa778
+ * </p>
* <p>
* This class is Not ThreadSafe
+ * </p>
*
* @see java.util.zip.CRC32
* @since 1.11
@@ -103,7 +107,7 @@ public class PureJavaCrc32 implements Checksum {
crc = (crc >>> 8) ^ T[(((crc ^ b) << 24) >>> 24)];
}
- /*
+ /**
* CRC-32 lookup tables generated by the polynomial 0xEDB88320.
* See also TestPureJavaCrc32.Table.
*/
diff --git a/src/main/java/org/apache/commons/codec/digest/PureJavaCrc32C.java
b/src/main/java/org/apache/commons/codec/digest/PureJavaCrc32C.java
index 50cf6794..6eb3ce18 100644
--- a/src/main/java/org/apache/commons/codec/digest/PureJavaCrc32C.java
+++ b/src/main/java/org/apache/commons/codec/digest/PureJavaCrc32C.java
@@ -25,19 +25,23 @@ import java.util.zip.Checksum;
/**
* A pure-java implementation of the CRC32 checksum that uses
* the CRC32-C polynomial, the same polynomial used by iSCSI
- * and implemented on many Intel chipsets supporting SSE4.2.
+ * and implemented on many Intel chipsets supporting SSE 4.2.
*
- * Copied from Hadoop 2.3.6:
+ * <p>
+ * Copied from Apache Hadoop 2.3.6:
* https://gitbox.apache.org/repos/asf?p=hadoop.git;a=blob_plain;
*
f=hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/util/PureJavaCrc32C.java;
* hb=2120de588b92b9f22b1cc4188761d6a8c61aa778
+ * </p>
* <p>
* This class is Not ThreadSafe
+ * </p>
+ *
* @since 1.11
*/
public class PureJavaCrc32C implements Checksum {
- /** the current CRC value, bit-flipped */
+ /** The current CRC value, bit-flipped */
private int crc;
/** Create a new PureJavaCrc32 object. */
diff --git a/src/main/java/org/apache/commons/codec/digest/Sha2Crypt.java
b/src/main/java/org/apache/commons/codec/digest/Sha2Crypt.java
index a0e33698..86abd586 100644
--- a/src/main/java/org/apache/commons/codec/digest/Sha2Crypt.java
+++ b/src/main/java/org/apache/commons/codec/digest/Sha2Crypt.java
@@ -31,11 +31,14 @@ import java.util.regex.Pattern;
* <p>
* Based on the C implementation released into the Public Domain by Ulrich
Drepper <[email protected]>
* http://www.akkadia.org/drepper/SHA-crypt.txt
+ * </p>
* <p>
* Conversion to Kotlin and from there to Java in 2012 by Christian Hammers
<[email protected]> and likewise put
* into the Public Domain.
+ * </p>
* <p>
* This class is immutable and thread-safe.
+ * </p>
*
* @since 1.7
*/
@@ -144,8 +147,10 @@ public class Sha2Crypt {
* <p>
* This is a nearly line by line conversion of the original C function.
The numbered comments are from the algorithm
* description, the short C-style ones from the original C code and the
ones with "Remark" from me.
+ * </p>
* <p>
* See {@link Crypt#crypt(String, String)} for details.
+ * </p>
*
* @param keyBytes
* plaintext to hash
diff --git a/src/main/java/org/apache/commons/codec/digest/UnixCrypt.java
b/src/main/java/org/apache/commons/codec/digest/UnixCrypt.java
index a7b8501b..94a3ea9b 100644
--- a/src/main/java/org/apache/commons/codec/digest/UnixCrypt.java
+++ b/src/main/java/org/apache/commons/codec/digest/UnixCrypt.java
@@ -26,14 +26,18 @@ import java.util.concurrent.ThreadLocalRandom;
* <p>
* This class only implements the traditional 56 bit DES based algorithm.
Please use DigestUtils.crypt() for a method
* that distinguishes between all the algorithms supported in the current
glibc's crypt().
+ * </p>
* <p>
* The Java implementation was taken from the JetSpeed Portal project (see
* org.apache.jetspeed.services.security.ldap.UnixCrypt).
+ * </p>
* <p>
* This class is slightly incompatible if the given salt contains characters
that are not part of the allowed range
* [a-zA-Z0-9./].
+ * </p>
* <p>
* This class is immutable and thread-safe.
+ * </p>
*
* @since 1.7
*/
diff --git a/src/main/java/org/apache/commons/codec/digest/XXHash32.java
b/src/main/java/org/apache/commons/codec/digest/XXHash32.java
index 708cd1a1..85afad92 100644
--- a/src/main/java/org/apache/commons/codec/digest/XXHash32.java
+++ b/src/main/java/org/apache/commons/codec/digest/XXHash32.java
@@ -55,6 +55,7 @@ public class XXHash32 implements Checksum {
private int totalLen;
private int pos;
+
/** Set to true when the state array has been updated since the last
reset. */
private boolean stateUpdated;
