From 6549373e8d172a69f0861b2331911641541d4250 Mon Sep 17 00:00:00 2001 From: Zihlu Wang Date: Fri, 15 Sep 2023 15:36:25 +0800 Subject: [PATCH] docs(global): Optimised javadocs. --- .../codecrafters/devkit/utils/AesUtil.java | 1 + .../codecrafters/devkit/utils/Base64Util.java | 7 +- .../codecrafters/devkit/utils/BranchUtil.java | 21 ++--- .../devkit/utils/ChainedCalcUtil.java | 26 ++---- .../codecrafters/devkit/utils/HashUtil.java | 6 +- .../codecrafters/devkit/utils/MapUtil.java | 6 +- .../cn/org/codecrafters/guid/GuidCreator.java | 5 +- .../guid/SnowflakeGuidCreator.java | 5 +- .../guid/exceptions/TimingException.java | 5 -- .../guid/exceptions/package-info.java | 4 - .../org/codecrafters/guid/package-info.java | 3 - .../autoconfiguration/PropertyGuard.java | 2 + .../authzero/AuthzeroTokenResolver.java | 8 +- .../config/AuthzeroTokenResolverConfig.java | 4 +- .../authzero/config/package-info.java | 5 -- .../simplejwt/authzero/package-info.java | 4 - .../codecrafters/simplejwt/SecretCreator.java | 2 +- .../codecrafters/simplejwt/TokenPayload.java | 8 +- .../codecrafters/simplejwt/TokenResolver.java | 6 +- .../annotations/ExcludeFromPayload.java | 12 +-- .../simplejwt/annotations/package-info.java | 1 - .../simplejwt/config/TokenResolverConfig.java | 2 - .../simplejwt/config/package-info.java | 2 - .../simplejwt/constants/PredefinedKeys.java | 13 +-- .../simplejwt/constants/TokenAlgorithm.java | 3 +- .../simplejwt/constants/package-info.java | 1 - .../UnsupportedAlgorithmException.java | 24 +++--- .../exceptions/WeakSecretException.java | 5 +- .../simplejwt/exceptions/package-info.java | 5 -- .../codecrafters/simplejwt/package-info.java | 5 -- .../simplejwt/jjwt/JjwtTokenResolver.java | 86 +++++++++++++++---- .../jjwt/config/JjwtTokenResolverConfig.java | 30 ++++++- .../simplejwt/jjwt/config/package-info.java | 5 -- .../simplejwt/jjwt/package-info.java | 4 - ...uthzeroTokenResolverAutoConfiguration.java | 8 +- .../GuidAutoConfiguration.java | 4 +- .../JjwtTokenResolverAutoConfiguration.java | 9 +- .../conditions/GuidCreatorCondition.java | 6 +- .../properties/SimpleJwtProperties.java | 14 ++- .../properties/package-info.java | 5 +- .../org/codecrafters/webcal/WebCalendar.java | 5 +- .../codecrafters/webcal/WebCalendarEvent.java | 2 +- .../codecrafters/webcal/WebCalendarNode.java | 2 +- .../webcal/config/Classification.java | 8 +- .../webcal/config/package-info.java | 1 - .../org/codecrafters/webcal/package-info.java | 1 - 46 files changed, 177 insertions(+), 214 deletions(-) diff --git a/devkit-utils/src/main/java/cn/org/codecrafters/devkit/utils/AesUtil.java b/devkit-utils/src/main/java/cn/org/codecrafters/devkit/utils/AesUtil.java index a0c916c..54a734c 100644 --- a/devkit-utils/src/main/java/cn/org/codecrafters/devkit/utils/AesUtil.java +++ b/devkit-utils/src/main/java/cn/org/codecrafters/devkit/utils/AesUtil.java @@ -39,6 +39,7 @@ import java.util.UUID; * * @author hubin@baomidou * @since 1.1.0 + * @version 1.1.0 */ @Slf4j public final class AesUtil { diff --git a/devkit-utils/src/main/java/cn/org/codecrafters/devkit/utils/Base64Util.java b/devkit-utils/src/main/java/cn/org/codecrafters/devkit/utils/Base64Util.java index e3548ab..96377d4 100644 --- a/devkit-utils/src/main/java/cn/org/codecrafters/devkit/utils/Base64Util.java +++ b/devkit-utils/src/main/java/cn/org/codecrafters/devkit/utils/Base64Util.java @@ -22,18 +22,15 @@ import java.nio.charset.StandardCharsets; import java.util.Base64; /** - *

* The {@code Base64Util} class provides static methods to encode and decode * strings using Base64 encoding. It utilizes the {@link Base64} class from the * Java standard library for performing the encoding and decoding operations. * This utility class offers convenient methods to encode and decode strings * with different character sets. - * *

* This class is designed as a final class with a private constructor to * prevent instantiation. All methods in this class are static, allowing easy * access to the Base64 encoding and decoding functionality. - * *

* Example usage: * 

@@ -47,15 +44,13 @@ import java.util.Base64;
  * String decoded = Base64Util.decode(encoded);
  * System.out.println("Decoded string: " + decoded);
  *
- * *

* Note: This utility class uses the default charset (UTF-8) if no * specific charset is provided. It is recommended to specify the charset * explicitly to ensure consistent encoding and decoding. - * * * @author Zihlu Wang - * @version 1.0.0 + * @version 1.1.0 * @since 1.0.0 */ public final class Base64Util { diff --git a/devkit-utils/src/main/java/cn/org/codecrafters/devkit/utils/BranchUtil.java b/devkit-utils/src/main/java/cn/org/codecrafters/devkit/utils/BranchUtil.java index 6e242b1..288f2f4 100644 --- a/devkit-utils/src/main/java/cn/org/codecrafters/devkit/utils/BranchUtil.java +++ b/devkit-utils/src/main/java/cn/org/codecrafters/devkit/utils/BranchUtil.java @@ -23,19 +23,14 @@ import java.util.function.BooleanSupplier; import java.util.function.Supplier; /** - *

* The BranchUtil class provides static methods to simplify conditional logic * in Java development by leveraging lambda expressions. It offers convenient * methods to replace verbose if...else statements with more concise and * expressive functional constructs. - * - * *

* Developers can use the methods in this utility class to streamline their * code, enhance readability, and promote a more functional style of * programming when dealing with branching logic and conditional statements. - * - * *

* Example: * 

@@ -67,7 +62,6 @@ import java.util.function.Supplier;
  *         // do something
  *     });
  *
- * *

* Note: * The {@link #and(Boolean...)} and {@link #or(Boolean...)} methods accept any @@ -75,7 +69,7 @@ import java.util.function.Supplier; * * @param the type of the result to be handled by the methods * @author Zihlu Wang - * @version 1.0.0 + * @version 1.1.0 * @see java.util.function.Supplier * @see java.util.function.BooleanSupplier * @see java.lang.Runnable @@ -164,15 +158,12 @@ public final class BranchUtil { } /** - *

* Handles the result of the boolean expressions by executing the * appropriate handler based on the result. - * *

* If the result is {@code true}, the {@code ifHandler} is executed. If the * result is {@code false} and an {@code elseHandler} is provided, it is * executed. - * *

* Returns the result of the executed handler. * @@ -181,7 +172,8 @@ public final class BranchUtil { * @param elseHandler the handler to be executed if the result is * {@code false} (optional) * @return the result of the executed handler, or {@code null} if no - * {@code elseHandler} is provided + * {@code elseHandler} is provided and the result of the evaluation is + * {@code false} */ public T handle(Supplier ifHandler, Supplier elseHandler) { if (this.result && Objects.nonNull(ifHandler)) { @@ -196,26 +188,23 @@ public final class BranchUtil { } /** - *

* Handles the result of the boolean expressions by executing the provided * handler if the result is {@code true}. - * *

* Returns the result of the executed handler. * * @param ifHandler the handler to be executed if the result is * {@code true} - * @return the result of the executed handler + * @return the result of the executed handler, or {@code null} if result of + * evaluation is {@code false} */ public T handle(Supplier ifHandler) { return handle(ifHandler, null); } /** - *

* Handles the result of the boolean expressions by executing the * appropriate handler based on the result. - * *

* If the result is {@code true}, the {@code ifHandler} is executed. If the * result is {@code false} and an {@code elseHandler} is provided, it is diff --git a/devkit-utils/src/main/java/cn/org/codecrafters/devkit/utils/ChainedCalcUtil.java b/devkit-utils/src/main/java/cn/org/codecrafters/devkit/utils/ChainedCalcUtil.java index 5817d88..98d69bf 100644 --- a/devkit-utils/src/main/java/cn/org/codecrafters/devkit/utils/ChainedCalcUtil.java +++ b/devkit-utils/src/main/java/cn/org/codecrafters/devkit/utils/ChainedCalcUtil.java @@ -17,6 +17,8 @@ package cn.org.codecrafters.devkit.utils; +import lombok.Getter; + import java.math.BigDecimal; import java.math.RoundingMode; import java.util.Objects; @@ -24,10 +26,7 @@ import java.util.function.BiFunction; import java.util.function.Function; /** - *

* Utility class for chained high-precision calculations using BigDecimal. - * - * *

* The ChainedCalcUtil class provides a convenient way to perform chained * high-precision calculations using BigDecimal. It allows users to perform @@ -35,8 +34,6 @@ import java.util.function.Function; * and division with customizable precision and scale. By using this utility * class, developers can achieve accurate results and avoid precision loss * in their calculations. - * - * *

* Usage: * 

@@ -85,7 +82,6 @@ import java.util.function.Function;
  *
* The above expressions perform various mathematical calculations using the * ChainedCalcUtil class. - * *

* Note: * The ChainedCalcUtil class internally uses BigDecimal to handle @@ -94,12 +90,17 @@ import java.util.function.Function; * for extremely large numbers or complex calculations. * * @author sunzsh - * @version 1.0.0 + * @version 1.1.0 * @see java.math.BigDecimal - * @since 9 Jul 2023 + * @since 1.0.0 */ +@Getter public final class ChainedCalcUtil { + /** + * -- GETTER -- + * Returns the current value as a BigDecimal. + */ private BigDecimal value; /** @@ -234,15 +235,6 @@ public final class ChainedCalcUtil { return baseOperator(otherValue -> this.value.divide(otherValue, scale, RoundingMode.HALF_UP), other, beforeOperateScale); } - /** - * Returns the current value as a BigDecimal. - * - * @return the current value as a BigDecimal - */ - public BigDecimal getValue() { - return value; - } - /** * Returns the current value as a BigDecimal with the specified scale. * diff --git a/devkit-utils/src/main/java/cn/org/codecrafters/devkit/utils/HashUtil.java b/devkit-utils/src/main/java/cn/org/codecrafters/devkit/utils/HashUtil.java index 37bb01b..bd33926 100644 --- a/devkit-utils/src/main/java/cn/org/codecrafters/devkit/utils/HashUtil.java +++ b/devkit-utils/src/main/java/cn/org/codecrafters/devkit/utils/HashUtil.java @@ -25,15 +25,12 @@ import java.util.Objects; import java.util.Optional; /** - *

* Utility class for performing hash operations on strings. - * *

* The HashUtil class provides convenient methods for calculating various hash * functions on strings, including MD2, MD5, SHA-1, SHA-224, SHA-256, SHA-384, * and SHA-512. It allows developers to easily obtain the hash value of a given * string using different algorithms. - * *

* Example usage: * 

@@ -60,7 +57,6 @@ import java.util.Optional;
  *
* The above examples demonstrate how to use the HashUtil class to calculate * hash values for a given string using different algorithms. - * *

* Note: * The hash functions provided by the HashUtil class are one-way hash @@ -69,7 +65,7 @@ import java.util.Optional; * password storage, but they should not be used for encryption purposes. * * @author Zihlu Wang - * @version 1.0.0 + * @version 1.1.0 * @see java.security.MessageDigest * @since 1.0.0 */ diff --git a/devkit-utils/src/main/java/cn/org/codecrafters/devkit/utils/MapUtil.java b/devkit-utils/src/main/java/cn/org/codecrafters/devkit/utils/MapUtil.java index 3d2cf36..d6e7644 100644 --- a/devkit-utils/src/main/java/cn/org/codecrafters/devkit/utils/MapUtil.java +++ b/devkit-utils/src/main/java/cn/org/codecrafters/devkit/utils/MapUtil.java @@ -24,17 +24,15 @@ import java.util.HashMap; import java.util.Map; /** - *

* MapUtil is a utility class that provides methods for converting objects to * maps and maps to objects. - * *

* It also provides methods for getting and setting field values using * reflection. * * @author Zihlu Wang - * @version 1.0.0 - * @since 16 Jul 2023 + * @version 1.1.0 + * @since 1.0.0 */ @Slf4j public final class MapUtil { diff --git a/guid/src/main/java/cn/org/codecrafters/guid/GuidCreator.java b/guid/src/main/java/cn/org/codecrafters/guid/GuidCreator.java index 8631876..8208b26 100644 --- a/guid/src/main/java/cn/org/codecrafters/guid/GuidCreator.java +++ b/guid/src/main/java/cn/org/codecrafters/guid/GuidCreator.java @@ -18,17 +18,14 @@ package cn.org.codecrafters.guid; /** - *

* The {@code GuidCreator} is a generic interface for generating globally unique * identifiers (GUIDs) of a specific type. - * *

* The type of ID is determined by the class implementing this interface. - * * * @param this represents the type of the Global Unique Identifier * @author Zihlu Wang - * @version 1.0.0 + * @version 1.1.0 * @since 1.0.0 */ public interface GuidCreator { diff --git a/guid/src/main/java/cn/org/codecrafters/guid/SnowflakeGuidCreator.java b/guid/src/main/java/cn/org/codecrafters/guid/SnowflakeGuidCreator.java index 878575f..9600b51 100644 --- a/guid/src/main/java/cn/org/codecrafters/guid/SnowflakeGuidCreator.java +++ b/guid/src/main/java/cn/org/codecrafters/guid/SnowflakeGuidCreator.java @@ -23,9 +23,7 @@ import java.time.LocalDateTime; import java.time.ZoneOffset; /** - *

* SnowflakeGuidCreator - GUID generator based on the Snowflake algorithm. - * *

* The SnowflakeGuidCreator generates unique identifiers using the Snowflake * algorithm, which combines a timestamp, worker ID, and data center ID to @@ -38,7 +36,6 @@ import java.time.ZoneOffset; *

  • 5 bits for worker ID
    • *
  • 12 bits for sequence number (per millisecond)
    • * - * *

    * When initializing the SnowflakeGuidCreator, you must provide the worker ID * and data center ID, ensuring they are within the valid range defined by the @@ -48,7 +45,7 @@ import java.time.ZoneOffset; * repeated timestamps. * * @author Zihlu Wang - * @version 1.0.0 + * @version 1.1.0 * @since 1.0.0 */ public final class SnowflakeGuidCreator implements GuidCreator { diff --git a/guid/src/main/java/cn/org/codecrafters/guid/exceptions/TimingException.java b/guid/src/main/java/cn/org/codecrafters/guid/exceptions/TimingException.java index 08c446c..952213b 100644 --- a/guid/src/main/java/cn/org/codecrafters/guid/exceptions/TimingException.java +++ b/guid/src/main/java/cn/org/codecrafters/guid/exceptions/TimingException.java @@ -18,27 +18,22 @@ package cn.org.codecrafters.guid.exceptions; /** - *

    * The TimingException class represents an exception that is thrown when there * is an error related to time sequence. - * *

    * This class extends the RuntimeException class, which means that instances of * TimingException do not need to be declared in a method or constructor's * throws clause. - * *

    * Instances of TimingException can be created with or without a message and a * cause. The message provides a description of the exception, while the cause * represents the underlying cause of the exception and provides additional * information about the error. - * *

    * TimingException is typically used to handle exceptions related to timing, * such as timeouts or synchronization issues. It is a subclass of * RuntimeException, which means it is an unchecked exception and does not need * to be caught or declared. - * * * @author Zihlu Wang * @since 1.0.0 diff --git a/guid/src/main/java/cn/org/codecrafters/guid/exceptions/package-info.java b/guid/src/main/java/cn/org/codecrafters/guid/exceptions/package-info.java index 565cad2..e12ea58 100644 --- a/guid/src/main/java/cn/org/codecrafters/guid/exceptions/package-info.java +++ b/guid/src/main/java/cn/org/codecrafters/guid/exceptions/package-info.java @@ -16,17 +16,14 @@ */ /** - *

    * This package contains the custom exception classes related to GUID * generation. These exceptions are thrown when there are issues or errors * during the generation or processing of global unique identifiers (GUIDs). - * *

    * The main exception class in this package is {@link * cn.org.codecrafters.guid.exceptions.TimingException}, which is a runtime * exception and serves as the base exception for all other custom exceptions * related to GUID generation. - * *

    * Custom exceptions in this package provide specific information about the * type of error that occurred during GUID generation, making it easier for @@ -34,7 +31,6 @@ * GUIDs. They are designed to enhance the robustness and reliability of the * GUID generation process by providing clear and meaningful error messages to * the developers. - * *

    * Developers using the GUID generation module should be aware of the possible * exceptions that can be thrown and handle them appropriately to ensure smooth diff --git a/guid/src/main/java/cn/org/codecrafters/guid/package-info.java b/guid/src/main/java/cn/org/codecrafters/guid/package-info.java index 8e7f31a..a9e9def 100644 --- a/guid/src/main/java/cn/org/codecrafters/guid/package-info.java +++ b/guid/src/main/java/cn/org/codecrafters/guid/package-info.java @@ -16,15 +16,12 @@ */ /** - *

    * The package provides a set of tools for generating globally unique * identifiers (GUIDs). - * *

    * The goal of this library is to provide an efficient, reliable way to * generate globally unique identifiers without requiring any specific * environment or configuration. - * *

    * Key features include: *

    * * @author Zihlu Wang - * @version 1.0.0 + * @version 1.1.0 * @since 1.0.0 */ @Getter @@ -50,7 +49,6 @@ public enum Classification { /** * Public classification level. - * *

    * Indicates that the calendar content is public and can be freely * distributed. @@ -59,7 +57,6 @@ public enum Classification { /** * Private classification level. - * *

    * Indicates that the calendar content is private and should not be shared * with others. @@ -68,7 +65,6 @@ public enum Classification { /** * Confidential classification level. - * *

    * Indicates that the calendar content is confidential and should be kept * strictly private. @@ -79,8 +75,6 @@ public enum Classification { /** * -- GETTER -- * Get the string representation of the classification level. - * - * @return the string representation of the classification level */ private final String classification; diff --git a/webcal/src/main/java/cn/org/codecrafters/webcal/config/package-info.java b/webcal/src/main/java/cn/org/codecrafters/webcal/config/package-info.java index 894709e..f0cf59d 100644 --- a/webcal/src/main/java/cn/org/codecrafters/webcal/config/package-info.java +++ b/webcal/src/main/java/cn/org/codecrafters/webcal/config/package-info.java @@ -20,7 +20,6 @@ * the configuration and settings of the web calendar module. It provides * various configurations and constants used in the generation and resolution * of iCalendar content. - * *

    The classes in this package include:

    *