docs(global): Optimised javadocs.

2023-09-15 15:36:25 +08:00
parent baa91f626a
commit 6549373e8d
46 changed files with 177 additions and 214 deletions
@@ -27,7 +27,7 @@ import java.util.Random;
 * passwords for various security-sensitive purposes.
 *
 * @author Zihlu Wang
- * @version 1.0.0
+ * @version 1.1.0
 * @since 1.0.0
 */
 public final class SecretCreator {
@@ -22,19 +22,19 @@ import java.util.Map;
 /**
 * <p>
 * TokenPayload - Interface for JWT Payload Data Classes.
- * 
+ *
 * <p>
 * The {@code TokenPayload} interface is used to mark a data class as suitable
 * for being used as the payload in a JSON Web Token (JWT). Any class
 * implementing this interface can be used to represent the payload data that
 * will be included in a JWT.
- * 
+ *
 * <p>
 * Implementing this interface indicates that the data class contains
 * information that needs to be securely transmitted and verified as part of a
 * JWT. The payload typically contains claims or attributes that provide
 * additional information about the JWT subject or context.
- * 
+ *
 * <p>
 * <b>Usage:</b>
 * To use a class as a JWT payload, simply implement the {@code TokenPayload}
@@ -45,8 +45,8 @@ import java.util.Map;
 * }
 * </pre>
 *
+ * @version 1.1.0
 * @since 1.0.0
- * @version 1.0.0
 */
 public interface TokenPayload {

@@ -22,25 +22,21 @@ import java.time.Duration;
 import java.util.Map;

 /**
- * <p>
 * The {@code TokenResolver} interface defines methods for creating,
 * extracting, and renewing tokens, particularly JSON Web Tokens (JWTs). It
 * provides a set of methods to generate tokens with various payload
 * configurations, extract payload from tokens, and renew expired tokens.
- *
 * <p>
 * <b>Token Creation:</b>
 * The interface provides overloaded methods for creating tokens with different
 * payload configurations, including expiration time, audience, subject, and
 * custom payload data. Clients can choose the appropriate method based on
 * their specific token requirements.
- *
 * <p>
 * <b>Token Extraction:</b>
 * The interface includes methods to extract payload information from a given
 * token. Clients can use these methods to obtain the payload data encoded in
 * the token.
- *
 * <p>
 * <b>Token Renewal:</b>
 * The interface also offers methods for token renewal. Clients can renew an
@@ -50,7 +46,7 @@ import java.util.Map;
 * @param <ResolvedTokenType> the type of the result obtained by the
 *                            third-party library when parsing JWTs
 * @author Zihlu Wang
- * @version 1.0.0
+ * @version 1.1.0
 * @since 1.0.0
 */
 public interface TokenResolver<ResolvedTokenType> {
@@ -28,9 +28,8 @@ import java.lang.annotation.Target;
 * excluded from being automatically injected into the JSON Web Token (JWT)
 * payload during token generation. When a property is annotated with this
 * annotation, it will not be included as part of the JWT payload.
- *
- *
- * <p><b>Usage:</b>
+ * <p>
+ * <b>Usage:</b>
 * To exclude a property from the JWT payload, annotate the property with
 * {@code @ExcludeFromPayload}:
 *
@@ -45,14 +44,15 @@ import java.lang.annotation.Target;
 *     // Getters and setters...
 * }
 * }</pre>
- *
- * <p><b>Note:</b>
+ * <p>
+ * <b>Note:</b>
 * This annotation should be used only on properties that are not intended to
 * be included in the JWT payload due to their sensitive nature or for other
 * reasons. It is important to carefully choose which properties are excluded
 * from the payload to ensure the JWT remains secure and efficient.
 *
- * @version 1.0.0
+ * @author Zihlu Wang
+ * @version 1.1.0
 * @since 1.0.0
 */
@Retention(RetentionPolicy.RUNTIME)
@@ -22,7 +22,6 @@
 * properties of a data class to exclude them from being included as part
 * of the JWT payload.
 *
- * @version 1.0.0
 * @since 1.0.0
 */
 package cn.org.codecrafters.simplejwt.annotations;
@@ -20,10 +20,8 @@ package cn.org.codecrafters.simplejwt.config;
 import cn.org.codecrafters.simplejwt.constants.TokenAlgorithm;

 /**
- * <p>
 * The TokenResolverConfig interface provides a mechanism to configure a
 * TokenResolver with algorithm functions.
- *
 * <p>
 * This generic interface is used to define the configuration details for a
 * TokenResolver that utilizes algorithm functions. The interface allows for
@@ -16,12 +16,10 @@
 */

 /**
- * <p>
 * The classes in this package provide configuration options and settings for
 * the Simple JWT library. They are used to customize the behavior of the
 * library and allow developers to fine-tune various aspects of JWT generation
 * and validation.
- *
 * <p>
 * Other configuration classes may be added in the future to support additional
 * customization options and features. Developers using the Simple JWT library
@@ -23,8 +23,8 @@ import java.util.List;
 * The {@code PredefinedKeys} class contains constants for standard JSON Web Token (JWT) claims. These constants
 * represent the names of the standard claims that can be included in a JWT payload. Developers can use these constants
 * when working with JWTs to ensure consistent naming of the claims.
- *
- * <p>The class provides the following standard JWT claim constants:
+ * <p>
+ * The class provides the following standard JWT claim constants:
 * <ul>
 *     <li>{@link #ISSUER}: Represents the "iss" (Issuer) claim.</li>
 *     <li>{@link #SUBJECT}: Represents the "sub" (Subject) claim.</li>
@@ -34,13 +34,14 @@ import java.util.List;
 *     <li>{@link #ISSUED_AT}: Represents the "iat" (Issued At) claim.</li>
 *     <li>{@link #JWT_ID}: Represents the "jti" (JWT ID) claim.</li>
 * </ul>
- *
- * <p>The class also contains a list of all the standard claim constants, accessible via the {@link #KEYS} field. This
+ * <p>
+ * The class also contains a list of all the standard claim constants, accessible via the {@link #KEYS} field. This
 * list can be useful for iterating through all the standard claims or checking for the presence of specific claims.
- *
- * <p>Note: This class is final and cannot be instantiated. It only serves as a utility class to hold the standard JWT
+ * <p>
+ * Note: This class is final and cannot be instantiated. It only serves as a utility class to hold the standard JWT
 * claim constants.
 *
+ * @version 1.1.0
 * @since 1.0.0
 */
 public final class PredefinedKeys {
@@ -25,7 +25,6 @@ import lombok.Getter;
 * cryptographic algorithms to be used for secure token generation and
 * validation. This enum provides a list of supported algorithms to ensure
 * consistent usage and avoid potential security issues.
- *
 * <p><b>Supported Algorithms:</b>
 * This enum includes the following supported algorithms:
 * <ul>
@@ -40,7 +39,7 @@ import lombok.Getter;
 *     <li>{@link TokenAlgorithm#ES512}: ECDSA with SHA-512</li>
 * </ul>
 *
- * @version 1.0.0
+ * @version 1.1.0
 * @since 1.0.0
 */
@Getter
@@ -22,6 +22,5 @@
 * configuration parameters.
 *
 * @since 1.0.0
- * @version 1.0.0
 */
 package cn.org.codecrafters.simplejwt.constants;
@@ -18,15 +18,14 @@
 package cn.org.codecrafters.simplejwt.exceptions;

 /**
- * <p>
 * This {@code UnsupportedAlgorithmException} is to indicates that the given
 * algorithm is not supported by TokenResolver yet.
- * 
 * <p>
 * To support a specified algorithm, you could
- * 
 *
 * @author Zihlu Wang
+ * @version 1.1.0
+ * @since 1.0.0
 */
 public class UnsupportedAlgorithmException extends RuntimeException {

@@ -51,14 +50,12 @@ public class UnsupportedAlgorithmException extends RuntimeException {
    }

    /**
-     * <p>
     * Constructs a new runtime exception with the specified detail message and
     * cause.
-     * 
-     * <p>Note that the detail message associated with
+     * <p>
+     * Note that the detail message associated with
     * {@code cause} is <i>not</i> automatically incorporated in
     * this runtime exception's detail message.
-     * 
     *
     * @param message the detail message (which is saved for later retrieval
     *                by the {@link #getMessage()} method).
@@ -95,13 +92,12 @@ public class UnsupportedAlgorithmException extends RuntimeException {
     * stack trace enabled or disabled.
     *
     * @param message            the detail message.
-     * @param cause              the cause.  (A {@code null} value is permitted,
-     *                           and indicates that the cause is nonexistent or unknown.)
-     * @param enableSuppression  whether or not suppression is enabled
-     *                           or disabled
-     * @param writableStackTrace whether or not the stack trace should
-     *                           be writable
-     * @since 1.7
+     * @param cause              the cause (A {@code null} value is permitted,
+     *                           and indicates that the cause is nonexistent or
+     *                           unknown.)
+     * @param enableSuppression  whether suppression is enabled or disabled
+     * @param writableStackTrace whether the stack trace should be writable
+     * @since 1.0.0
     */
    public UnsupportedAlgorithmException(String message, Throwable cause, boolean enableSuppression, boolean writableStackTrace) {
        super(message, cause, enableSuppression, writableStackTrace);
@@ -18,9 +18,12 @@
 package cn.org.codecrafters.simplejwt.exceptions;

 /**
- * WeakSecretException
+ * This Exception indicates that your secret is too weak to be used in signing
+ * JWTs.
 *
 * @author Zihlu Wang
+ * @version 1.1.0
+ * @since 1.0.0
 */
 public class WeakSecretException extends RuntimeException {

@@ -16,13 +16,10 @@
 */

 /**
- * <p>
 * The {@code cn.org.codecrafters.simplejwt.exceptions} package contains
 * custom exception classes related to the Simple JWT library. These
 * exceptions are thrown when there are issues or errors during the generation
 * , validation, or processing of JSON Web Tokens (JWTs) in Java applications.
- *
- *
 * <p>
 * Custom exception classes in this package are designed to enhance the
 * robustness and reliability of the JWT handling process by providing clear
@@ -30,8 +27,6 @@
 * identify and troubleshoot issues related to JWT generation, validation, or
 * extraction and ensure smooth operation and error handling in their
 * applications.
- *
- *
 * <p>
 * Developers using the Simple JWT library should be aware of the possible
 * exceptions that can be thrown and handle them appropriately to ensure secure
@@ -16,7 +16,6 @@
 */

 /**
- * <p>
 * The {@code cn.org.codecrafters.simplejwt} package is the core package of the
 * Simple JWT project, which provides a lightweight and easy-to-use library for
 * working with JSON Web Tokens (JWTs) in Java applications. JWT is a
@@ -24,16 +23,12 @@
 * used to secure web and mobile applications. This library aims to simplify
 * the JWT handling process and provide convenient abstractions for JWT
 * generation, validation, and extraction.
- * 
- *
 * <p>
 * The Simple JWT library is designed to be flexible and customizable, allowing
 * developers to use different algorithms, token resolvers, and token payload
 * classes based on their specific application requirements. It aims to
 * simplify the JWT handling process while maintaining security and best
 * practices for working with JWTs.
- * 
- *
 * <p>
 * Developers should refer to the official documentation and examples for the
 * Simple JWT project to understand how to use the library effectively and