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

2023-07-31 21:43:09 +08:00
parent 373fbf9083
commit 715ae6db3a
28 changed files with 627 additions and 133 deletions
@@ -20,17 +20,21 @@ package cn.org.codecrafters.simplejwt;
 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}
@@ -40,6 +44,7 @@ import java.util.Map;
 *     // Class implementation with payload data...
 * }
 * </pre>
+ * </p>
 *
 * @since 1.0.0
 * @version 1.0.0
@@ -21,26 +21,31 @@ 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 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
@@ -30,6 +30,7 @@ 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>
 *
 * <p><b>Usage:</b>
 * To exclude a property from the JWT payload, annotate the property with
@@ -40,18 +41,20 @@ import java.lang.annotation.Target;
 *     private String username;
 *
 *     // This property will not be included in the JWT payload
- *     {@literal @}ExcludeFromPayload
+ *     @ExcludeFromPayload
 *     private String sensitiveData;
 *
 *     // 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
@@ -20,13 +20,16 @@ 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>
 * <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
@@ -0,0 +1,35 @@
+/*
+ * Copyright (C) 2023 CodeCraftersCN.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * <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>
+ *
+ * <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
+ */
+package cn.org.codecrafters.simplejwt.config;
@@ -20,12 +20,47 @@ package cn.org.codecrafters.simplejwt.constants;
 import java.util.List;

 /**
- * PredefinedKeys
+ * <p>
+ * This class contains predefined keys that are commonly used in JSON Web
+ * Tokens (JWT).
+ * </p>
 *
- * @author Zihlu Wang
+ * <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>
+ * 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>
+ *
+ * @since 1.0.0
 */
 public final class PredefinedKeys {

-    public static final List<String> KEYS = List.of("aud", "sub", "nbf", "iss", "exp", "iat", "jti");
+    // Constants for standard JWT claims
+    public static final String ISSUER = "iss";

+    public static final String SUBJECT = "sub";
+
+    public static final String AUDIENCE = "aud";
+
+    public static final String EXPIRATION_TIME = "exp";
+
+    public static final String NOT_BEFORE = "nbf";
+
+    public static final String ISSUED_AT = "iat";
+
+    public static final String JWT_ID = "jti";
+
+    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);
 }
@@ -17,21 +17,16 @@

 package cn.org.codecrafters.simplejwt.constants;

-import ch.qos.logback.core.subst.Token;
 import lombok.Getter;

-import java.lang.reflect.Array;
-import java.util.Arrays;
-import java.util.List;
-import java.util.stream.Stream;
-
 /**
+ * <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>
@@ -45,9 +40,10 @@ import java.util.stream.Stream;
 *     <li>{@link TokenAlgorithm#ES384}: ECDSA with SHA-384</li>
 *     <li>{@link TokenAlgorithm#ES512}: ECDSA with SHA-512</li>
 * </ul>
+ * </p>
 *
- * @since 1.0.0
 * @version 1.0.0
+ * @since 1.0.0
 */
@Getter
 public enum TokenAlgorithm {
@@ -18,18 +18,21 @@
 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
 */
 public class UnsupportedAlgorithmException extends RuntimeException {

    /**
-     * Constructs a new runtime exception with {@code null} as its
-     * detail message.  The cause is not initialized, and may subsequently be
+     * Constructs a new runtime exception with {@code null} as its detail
+     * message. The cause is not initialized, and may subsequently be
     * initialized by a call to {@link #initCause}.
     */
    public UnsupportedAlgorithmException() {
@@ -48,10 +51,14 @@ 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
+     * 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).
@@ -0,0 +1,43 @@
+/*
+ * Copyright (C) 2023 CodeCraftersCN.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * <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>
+ *
+ * <p>
+ * Custom exception classes in this package are designed to enhance the
+ * robustness and reliability of the JWT handling process by providing clear
+ * and meaningful error messages to the developers. They help developers
+ * 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
+ */
+package cn.org.codecrafters.simplejwt.exceptions;
@@ -16,8 +16,30 @@
 */

 /**
- * package-info
+ * <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
+ * widely-used standard for representing claims between two parties, typically
+ * 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>
 *
- * @author Zihlu Wang
+ * <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>
+ *
+ * <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
 */
 package cn.org.codecrafters.simplejwt;