docs: Fix all docs from one <p> represents for a paragraph

2023-07-31 22:53:09 +08:00
parent 715ae6db3a
commit 748e474a82
34 changed files with 220 additions and 184 deletions
@@ -22,19 +22,19 @@ import java.util.Map;
 /**
 * <p>
 * TokenPayload - Interface for JWT Payload Data Classes.
- * </p>
+ * 
 * <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>
+ * 
 * <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>
+ * 
 * <p>
 * <b>Usage:</b>
 * To use a class as a JWT payload, simply implement the {@code TokenPayload}
@@ -44,7 +44,6 @@ import java.util.Map;
 *     // Class implementation with payload data...
 * }
 * </pre>
- * </p>
 *
 * @since 1.0.0
 * @version 1.0.0
@@ -26,26 +26,25 @@ import java.util.Map;
 * extracting, and renewing tokens, particularly JSON Web Tokens (JWTs). It
 * provides a set of methods to generate tokens with various payload
 * configurations, extract payloads from tokens, and renew expired tokens.
- * </p>
+ *
 * <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>
+ *
 * <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>
+ *
 * <p>
 * <b>Token Renewal:</b>
 * The interface also offers methods for token renewal. Clients can renew an
 * expired token by providing a new expiration time, audience, subject, and
 * optional custom payload data.
- * </p>
 *
 * @param <ResolvedTokenType> the type of the result obtained by the
 *                            third-party library when parsing JWTs
@@ -23,14 +23,12 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;

 /**
- * <h3>ExcludeFromPayload</h3>
- * <h4>Annotation to Exclude Property from JWT Payload.</h4>
 * <p>
 * This annotation is used to mark a property of a data class that should be
 * 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>
+ *
 *
 * <p><b>Usage:</b>
 * To exclude a property from the JWT payload, annotate the property with
@@ -47,17 +45,15 @@ import java.lang.annotation.Target;
 *     // Getters and setters...
 * }
 * }</pre>
- * </p>
 *
 * <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.
- * </p>
 *
- * @since 1.0.0
 * @version 1.0.0
+ * @since 1.0.0
 */
@Retention(RetentionPolicy.RUNTIME)
@Target({ElementType.FIELD})
@@ -23,13 +23,13 @@ import cn.org.codecrafters.simplejwt.constants.TokenAlgorithm;
 * <p>
 * The TokenResolverConfig interface provides a mechanism to configure a
 * TokenResolver with algorithm functions.
- * </p>
+ * 
 * <p>
 * This generic interface is used to define the configuration details for a
 * TokenResolver that utilizes algorithm functions. The interface allows for
 * specifying algorithm functions corresponding to different TokenAlgorithm
 * instances supported by the TokenResolver implementation.
- * </p>
+ * 
 *
 * @param <AlgorithmFunction> the type representing algorithm functions used by
 *                            the TokenResolver
@@ -21,14 +21,12 @@
 * 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>
 *
 * <p>
 * Other configuration classes may be added in the future to support additional
 * customization options and features. Developers using the Simple JWT library
 * should be familiar with the available configuration options to ensure proper
 * integration and usage of the library.
- * </p>
 *
 * @since 1.0.0
 */
@@ -20,47 +20,77 @@ package cn.org.codecrafters.simplejwt.constants;
 import java.util.List;

 /**
- * <p>
- * This class contains predefined keys that are commonly used in JSON Web
- * Tokens (JWT).
- * </p>
+ * 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>
- * JWTs consist of a set of claims represented as key-value pairs. These claims
- * store various pieces of information, such as the subject, issuer, expiration
- * time, and more. To ensure consistency and avoid spelling mistakes, this
- * class provides constants for the standard keys used in JWT claims.
- * </p>
+ * <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>
+ *     <li>{@link #AUDIENCE}: Represents the "aud" (Audience) claim.</li>
+ *     <li>{@link #EXPIRATION_TIME}: Represents the "exp" (Expiration Time) claim.</li>
+ *     <li>{@link #NOT_BEFORE}: Represents the "nbf" (Not Before) claim.</li>
+ *     <li>{@link #ISSUED_AT}: Represents the "iat" (Issued At) claim.</li>
+ *     <li>{@link #JWT_ID}: Represents the "jti" (JWT ID) claim.</li>
+ * </ul>
 *
- * <p>
- * Developers using this JWT library can use these predefined keys to set and
- * retrieve claims in a safer and more readable way. By using constants instead
- * of plain strings, it helps prevent typos and makes the code more
- * maintainable.
- * </p>
+ * <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
+ * claim constants.
 *
 * @since 1.0.0
 */
 public final class PredefinedKeys {

-    // Constants for standard JWT claims
+    /**
+     * Constant representing the "iss" (Issuer) claim in a JWT payload.
+     */
    public static final String ISSUER = "iss";

+    /**
+     * Constant representing the "sub" (Subject) claim in a JWT payload.
+     */
    public static final String SUBJECT = "sub";

+    /**
+     * Constant representing the "aud" (Audience) claim in a JWT payload.
+     */
    public static final String AUDIENCE = "aud";

+    /**
+     * Constant representing the "exp" (Expiration Time) claim in a JWT payload.
+     */
    public static final String EXPIRATION_TIME = "exp";

+    /**
+     * Constant representing the "nbf" (Not Before) claim in a JWT payload.
+     */
    public static final String NOT_BEFORE = "nbf";

+    /**
+     * Constant representing the "iat" (Issued At) claim in a JWT payload.
+     */
    public static final String ISSUED_AT = "iat";

+    /**
+     * Constant representing the "jti" (JWT ID) claim in a JWT payload.
+     */
    public static final String JWT_ID = "jti";

+    /**
+     * List containing all the standard JWT claim constants.
+     */
+    public static final List<String> KEYS = List.of(ISSUER, SUBJECT, AUDIENCE, EXPIRATION_TIME, NOT_BEFORE, ISSUED_AT, JWT_ID);
+
+    /**
+     * Private constructor to prevent instantiation of the {@code PredefinedKeys} class.
+     * This class is intended to be used as a utility class with only static constants and methods.
+     */
    private PredefinedKeys() {
        // Private constructor to prevent instantiation
    }
-
-    public static final List<String> KEYS = List.of(ISSUER, SUBJECT, AUDIENCE, EXPIRATION_TIME, NOT_BEFORE, ISSUED_AT, JWT_ID);
 }
+
@@ -20,13 +20,12 @@ package cn.org.codecrafters.simplejwt.constants;
 import lombok.Getter;

 /**
- * <p>
 * The {@code TokenAlgorithm} enum class defines the algorithms that can be
 * used for signing and verifying JSON Web Tokens (JWT). JWT allows various
 * 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>
+ *
 * <p><b>Supported Algorithms:</b>
 * This enum includes the following supported algorithms:
 * <ul>
@@ -40,21 +39,56 @@ import lombok.Getter;
 *     <li>{@link TokenAlgorithm#ES384}: ECDSA with SHA-384</li>
 *     <li>{@link TokenAlgorithm#ES512}: ECDSA with SHA-512</li>
 * </ul>
- * </p>
 *
 * @version 1.0.0
 * @since 1.0.0
 */
@Getter
 public enum TokenAlgorithm {
+
+    /**
+     * HMAC using SHA-256
+     */
    HS256,
+
+    /**
+     * HMAC using SHA-384
+     */
    HS384,
+
+    /**
+     * HMAC using SHA-512
+     */
    HS512,
+
+    /**
+     * RSASSA-PKCS-v1_5 using SHA-256
+     */
    RS256,
+
+    /**
+     * RSASSA-PKCS-v1_5 using SHA-384
+     */
    RS384,
+
+    /**
+     * RSASSA-PKCS-v1_5 using SHA-512
+     */
    RS512,
+
+    /**
+     * ECDSA using P-256 and SHA-256
+     */
    ES256,
+
+    /**
+     * ECDSA using P-384 and SHA-384
+     */
    ES384,
+
+    /**
+     * ECDSA using P-521 and SHA-512
+     */
    ES512,
    ;

@@ -21,10 +21,10 @@ package cn.org.codecrafters.simplejwt.exceptions;
 * <p>
 * This {@code UnsupportedAlgorithmException} is to indicates that the given
 * algorithm is not supported by TokenResolver yet.
- * </p>
+ * 
 * <p>
 * To support a specified algorithm, you could
- * </p>
+ * 
 *
 * @author Zihlu Wang
 */
@@ -54,11 +54,11 @@ public class UnsupportedAlgorithmException extends RuntimeException {
     * <p>
     * Constructs a new runtime exception with the specified detail message and
     * cause.
-     * </p>
+     * 
     * <p>Note that the detail message associated with
     * {@code cause} is <i>not</i> automatically incorporated in
     * this runtime exception's detail message.
-     * </p>
+     * 
     *
     * @param message the detail message (which is saved for later retrieval
     *                by the {@link #getMessage()} method).
@@ -21,7 +21,7 @@
 * 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>
+ *
 *
 * <p>
 * Custom exception classes in this package are designed to enhance the
@@ -30,13 +30,12 @@
 * identify and troubleshoot issues related to JWT generation, validation, or
 * extraction and ensure smooth operation and error handling in their
 * applications.
- * </p>
+ *
 *
 * <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
 * and reliable JWT handling in their Java applications.
- * </p>
 *
 * @since 1.0.0
 */
@@ -24,7 +24,7 @@
 * 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>
+ * 
 *
 * <p>
 * The Simple JWT library is designed to be flexible and customizable, allowing
@@ -32,13 +32,13 @@
 * 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>
+ * 
 *
 * <p>
 * Developers should refer to the official documentation and examples for the
 * Simple JWT project to understand how to use the library effectively and
 * securely in their Java applications.
- * </p>
+ * 
 *
 * @since 1.0.0
 */