onixbyte/onixbyte-bom
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(global): Improve documentation comments

Browse Source 
Enriched the content of the documentation to ensure every package and
class has proper documentation comments; Modified the formatting for
consistent and neat presentation.
This commit is contained in:
Zihlu Wang
2023-07-30 02:27:05 +08:00
parent 89837f78f3
commit 65daccf478
19 changed files with 616 additions and 186 deletions
Download Patch File Download Diff File Expand all files Collapse all files
guid/src/main/java/cn/org/codecrafters/devkit/guid/GuidCreator.java
+2 -1
View File
@@ -18,7 +18,7 @@
package cn.org.codecrafters.devkit.guid;
/**
* The `GuidCreator` is a generic interface for generating globally unique
* The {@code GuidCreator} is a generic interface for generating globally unique
* identifiers (GUIDs) of a specific type.
* <p>
* The type of ID is determined by the class implementing this interface.
@@ -32,6 +32,7 @@ public interface GuidCreator<IdType> {
/**
* Generates and returns the next globally unique ID.
* <p>
* The exact implementation of how the globally unique ID is generated and
* returned will depend on the class implementing this method.
*
guid/src/main/java/cn/org/codecrafters/devkit/guid/SnowflakeGuidCreator.java
+32 -21
View File
@@ -23,23 +23,28 @@ import java.time.LocalDateTime;
import java.time.ZoneOffset;
/**
* SnowflakeGuidCreator is a GUID generator based on the Snowflake algorithm.
* It generates unique identifiers using a combination of timestamp, worker ID,
* and data center ID.
* SnowflakeGuidCreator - GUID generator based on the Snowflake algorithm.
*
* <p>The Snowflake algorithm allows for the generation of 64-bit long integers,
* with the following bit distribution:
* - 1 bit for sign
* - 41 bits for timestamp (in milliseconds)
* - 5 bits for data center ID
* - 5 bits for worker ID
* - 12 bits for sequence number (per millisecond)
* <p>
* The SnowflakeGuidCreator generates unique identifiers using the Snowflake
* algorithm, which combines a timestamp, worker ID, and data center ID to
* create 64-bit long integers. The bit distribution for the generated IDs is
* as follows:
* <ul>
* <li>1 bit for sign</li>
* <li>41 bits for timestamp (in milliseconds)</li>
* <li>5 bits for data center ID</li>
* <li>5 bits for worker ID</li>
* <li>12 bits for sequence number (per millisecond)</li>
* </ul>
*
* <p>The worker ID and data center ID must be specified during initialization,
* and they must be within the valid range defined by the bit size.
* The generator maintains an internal sequence number that increments for IDs
* generated within the same millisecond. If the system clock moves backwards,
* an exception is thrown to avoid generating IDs with repeated timestamps.
* <p>
* When initializing the SnowflakeGuidCreator, you must provide the worker ID
* and data center ID, ensuring they are within the valid range defined by the
* bit size. The generator maintains an internal sequence number that
* increments for IDs generated within the same millisecond. If the system
* clock moves backward, an exception is thrown to prevent generating IDs with
* repeated timestamps.
*
* @author Zihlu Wang
* @version 1.0.0
@@ -48,7 +53,9 @@ import java.time.ZoneOffset;
public final class SnowflakeGuidCreator implements GuidCreator<Long> {
/**
* Default Custom Epoch (January 1, 2015, Midnight UTC = 2015-01-01T00:00:00Z)
* Default custom epoch.
*
* @value 2015-01-01T00:00:00Z
*/
private static final long DEFAULT_CUSTOM_EPOCH = 1_420_070_400_000L;
@@ -88,7 +95,8 @@ public final class SnowflakeGuidCreator implements GuidCreator<Long> {
private long lastTimestamp = -1L;
/**
* Constructs a SnowflakeGuidGenerator with the default start epoch and custom worker ID, data center ID.
* Constructs a SnowflakeGuidGenerator with the default start epoch and
* custom worker ID, data center ID.
*
* @param workerId the worker ID (between 0 and 31).
* @param dataCentreId the data center ID (between 0 and 31).
@@ -98,13 +106,16 @@ public final class SnowflakeGuidCreator implements GuidCreator<Long> {
}
/**
* Constructs a SnowflakeGuidGenerator with a custom epoch, worker ID, and data center ID.
* Constructs a SnowflakeGuidGenerator with a custom epoch, worker ID, and
* data center ID.
*
* @param startEpoch the custom epoch timestamp (in milliseconds) to start generating IDs from
* @param startEpoch the custom epoch timestamp (in milliseconds) to
* start generating IDs from
* @param workerId the worker ID (between 0 and 31)
* @param dataCentreId the data center ID (between 0 and 31)
* @throws IllegalArgumentException if the start epoch is greater than the current timestamp,
* or if the worker ID or data center ID is out of range
* @throws IllegalArgumentException if the start epoch is greater than the
* current timestamp, or if the worker ID
* or data center ID is out of range
*/
public SnowflakeGuidCreator(long startEpoch, long workerId, long dataCentreId) {
if (startEpoch > currentTimestamp()) {
guid/src/main/java/cn/org/codecrafters/devkit/guid/exceptions/TimingException.java
+21 -18
View File
@@ -18,20 +18,22 @@
package cn.org.codecrafters.devkit.guid.exceptions;
/**
* The TimingException class represents an exception that is thrown when there is an error related
* to time sequence.
* The TimingException class represents an exception that is thrown when there
* is an error related to time sequence.
* <p>
* 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.
* 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.
* <p>
* 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.
* <p>
* 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.
* 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.
* <p>
* 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
@@ -39,14 +41,15 @@ package cn.org.codecrafters.devkit.guid.exceptions;
public class TimingException extends RuntimeException {
/**
* A custom exception that is thrown when there is an issue with timing or scheduling.
* A custom exception that is thrown when there is an issue with timing or
* scheduling.
*/
public TimingException() {
}
/**
* A custom exception that is thrown when there is an issue with timing or scheduling with
* customized error message.
* A custom exception that is thrown when there is an issue with timing or
* scheduling with customized error message.
*
* @param message customized message
*/
@@ -55,8 +58,8 @@ public class TimingException extends RuntimeException {
}
/**
* A custom exception that is thrown when there is an issue with timing or scheduling with
* customized error message.
* A custom exception that is thrown when there is an issue with timing or
* scheduling with customized error message.
*
* @param message customized message
* @param cause the cause of this exception
@@ -66,8 +69,8 @@ public class TimingException extends RuntimeException {
}
/**
* A custom exception that is thrown when there is an issue with timing or scheduling with
* customized error message.
* A custom exception that is thrown when there is an issue with timing or
* scheduling with customized error message.
*
* @param cause the cause of this exception
*/
guid/src/main/java/cn/org/codecrafters/devkit/guid/exceptions/package-info.java
+23
View File
@@ -0,0 +1,23 @@
/*
* 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.
*/
/**
* The package provides all exceptions be used by module guid.
*
* @since 1.0.0
*/
package cn.org.codecrafters.devkit.guid.exceptions;
guid/src/main/java/cn/org/codecrafters/devkit/guid/package-info.java
+3 -3
View File
@@ -25,9 +25,9 @@
* <p>
* Key features include:
* <ul>
* <li>Efficient generation of globally unique identifiers</li>
* <li>High performance and quick response</li>
* <li>Easy to integrate</li>
* <li>Efficient generation of globally unique identifiers</li>
* <li>High performance and quick response</li>
* <li>Easy to integrate</li>
* </ul>
*
* @since 1.0.0