From 6b4d2791552b8c44137d1a05a38b4d85c288aa2b Mon Sep 17 00:00:00 2001
From: VampireAchao <achao@hutool.cn>
Date: Tue, 27 Feb 2024 01:28:38 +0800
Subject: [PATCH] =?UTF-8?q?[improve]=20=E4=BC=98=E5=8C=96=E3=80=81?=
 =?UTF-8?q?=E5=AE=8C=E5=96=84=E6=B3=A8=E9=87=8A?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../hutool/core/date/chinese/ShiChen.java     | 55 ++++++++++++++++---
 1 file changed, 46 insertions(+), 9 deletions(-)

diff --git a/hutool-core/src/main/java/org/dromara/hutool/core/date/chinese/ShiChen.java b/hutool-core/src/main/java/org/dromara/hutool/core/date/chinese/ShiChen.java
index a94584dc0..799ac571f 100644
--- a/hutool-core/src/main/java/org/dromara/hutool/core/date/chinese/ShiChen.java
+++ b/hutool-core/src/main/java/org/dromara/hutool/core/date/chinese/ShiChen.java
@@ -11,23 +11,31 @@ import java.util.Map;
 
 /**
  * 时辰转换器，支持宋以后的二十四时辰制度。
- * <p>
- * 该转换器能够处理包含“时”、“初”或“正”后缀的长安时辰描述，并根据这些描述自动返回相应的现代时间段。
- * 对于“初”和“正”的描述，分别对应每个时辰的前半段和后半段，而不带后缀的时辰描述则表示该时辰的整个时间段。
+ * <p>本转换器提供以下功能：
+ * <ul>
+ * <li>处理包含“时”、“初”或“正”后缀的长安时辰描述，并自动返回相应的现代时间段。
+ * “初”和“正”分别对应每个时辰的前半段和后半段，而不带后缀的“时”描述则涵盖该时辰的完整时间段。</li>
+ * <li>根据小时数转换为相应的长安时辰描述，通过{@code isAbs}参数控制是否包含“初”或“正”。</li>
+ * </ul>
  * </p>
  * <p>
- * 此外，该转换器还提供了根据小时数转换为对应的长安时辰描述的功能，通过isAbs参数可以控制返回的描述是否包含“初”或“正”。
+ * 异常情况：
+ * <ul>
+ * <li>如果输入的长安时辰描述无效或不被识别，{@code toModernTime} 方法将抛出 {@code IllegalArgumentException}。</li>
+ * <li>同样，如果{@code toShiChen}方法接收到无效的小时数，将返回“未知”。</li>
+ * </ul>
  * </p>
  * <p>
  * 示例：
  * <ul>
- * <li>toModernTime("子时") 返回的时间段从23点开始到1点结束。</li>
- * <li>toModernTime("子初") 返回的时间段从23点开始到0点结束。</li>
- * <li>toModernTime("子正") 返回的时间段从0点开始到1点结束。</li>
- * <li>toShiChen(0, false) 返回“子正”。</li>
- * <li>toShiChen(0, true) 返回“子时”。</li>
+ * <li>{@code toModernTime("子时")} 返回的时间段从23点开始到1点结束。</li>
+ * <li>{@code toModernTime("子初")} 返回的时间段从23点开始到0点结束。</li>
+ * <li>{@code toModernTime("子正")} 返回的时间段从0点开始到1点结束。</li>
+ * <li>{@code toShiChen(0, false)} 返回“子正”。</li>
+ * <li>{@code toShiChen(0, true)} 返回“子时”。</li>
  * </ul>
  * </p>
+ *
  * @author achao@hutool.cn
  */
 public class ShiChen {
@@ -59,6 +67,21 @@ public class ShiChen {
 		}
 	}
 
+	/**
+	 * 将长安时辰描述转换为现代时间段。
+	 * <p>
+	 * 示例：
+	 * <ul>
+	 * <li>{@code toModernTime("子时")} 返回的时间段从23点开始到1点结束。</li>
+	 * <li>{@code toModernTime("子初")} 返回的时间段从23点开始到0点结束。</li>
+	 * <li>{@code toModernTime("子正")} 返回的时间段从0点开始到1点结束。</li>
+	 * </ul>
+	 * </p>
+	 *
+	 * @param shiChen 长安时辰描述，可以是“时”、“初”或“正”结尾。
+	 * @return {@link DateBetween} 对象，表示起始和结束时间。
+	 * @throws IllegalArgumentException 如果输入的长安时辰描述无效。
+	 */
 	public static DateBetween toModernTime(String shiChen) {
 		if (StrUtil.isEmpty(shiChen)) {
 			throw new IllegalArgumentException("Invalid shiChen");
@@ -91,6 +114,20 @@ public class ShiChen {
 		return DateBetween.of(startDate, endDate);
 	}
 
+	/**
+	 * 根据给定的小时数转换为对应的长安时辰描述。
+	 * <p>
+	 * 示例：
+	 * <ul>
+	 * <li>{@code toShiChen(0, false)} 返回“子正”。</li>
+	 * <li>{@code toShiChen(0, true)} 返回“子时”。</li>
+	 * </ul>
+	 * </p>
+	 *
+	 * @param hour 小时数，应在0到23之间。
+	 * @param isAbs 是否返回绝对时辰描述（即包含“时”后缀），而不是“初”或“正”。
+	 * @return 长安时辰描述，如果小时数无效，则返回“未知”。
+	 */
 	public static String toShiChen(int hour, boolean isAbs) {
 		String result = hourToShiChenAbsMap.getOrDefault(hour, "未知");
 		if (!isAbs && !result.equals("未知")) {