From 20bef9263b6e3769a94b2a51f6798323bda6b974 Mon Sep 17 00:00:00 2001 From: Timi Date: Tue, 13 Jan 2026 15:33:25 +0800 Subject: [PATCH] add comprehensive javadoc comments for all classes - Add class-level documentation for all mapper and multilingual classes - Add complete javadoc for all public methods with @param and @return tags - Add field-level comments for better code readability - Improve documentation for initialization blocks and constructors Co-Authored-By: Claude Sonnet 4.5 --- .gitignore | 4 +++ .../lang/mapper/AbstractLanguageMapper.java | 34 ++++++++++++++++++ .../imyeyu/lang/mapper/FileLanguageMap.java | 7 ++++ .../com/imyeyu/lang/mapper/LanguageMap.java | 27 ++++++++++++++ .../lang/mapper/PropertiesLanguageMap.java | 7 ++++ .../lang/mapper/ResourcesLanguageMap.java | 8 +++++ .../imyeyu/lang/multi/FileMultilingual.java | 20 +++++++++++ .../com/imyeyu/lang/multi/Multilingual.java | 35 +++++++++++++++++++ .../lang/multi/ResourcesMultilingual.java | 23 ++++++++++++ 9 files changed, 165 insertions(+) diff --git a/.gitignore b/.gitignore index 5ff6309..0ec825b 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,7 @@ +/.claude +/CLAUDE.md +/AGENTS.md + target/ !.mvn/wrapper/maven-wrapper.jar !**/src/main/**/target/ diff --git a/src/main/java/com/imyeyu/lang/mapper/AbstractLanguageMapper.java b/src/main/java/com/imyeyu/lang/mapper/AbstractLanguageMapper.java index c09b5d1..7d3fa37 100644 --- a/src/main/java/com/imyeyu/lang/mapper/AbstractLanguageMapper.java +++ b/src/main/java/com/imyeyu/lang/mapper/AbstractLanguageMapper.java @@ -7,35 +7,69 @@ import com.imyeyu.utils.StringInterpolator; import java.util.Map; /** + * 抽象语言映射器，提供语言映射的基础实现，提供字符串插值、调试模式等基础功能 + * * @author 夜雨 * @version 2024-04-01 16:25 */ public abstract class AbstractLanguageMapper implements LanguageMapping { + /** 字符串插值器，用于处理占位符替换 */ protected final StringInterpolator INTERPOLATOR = StringInterpolator.createDollarInterpolator(); + /** 当前映射器所属语言 */ protected final Language.Enum language; + /** 是否启用调试模式，启用后将抛出异常而不是返回默认值 */ protected boolean isDebugging = false; + /** + * 构造语言映射器 + * + * @param language 所属语言 + */ public AbstractLanguageMapper(Language.Enum language) { this.language = language; } + /** + * 获取当前映射器所属语言 + * + * @return 语言枚举 + */ public Language.Enum getLanguage() { return language; } + /** + * 设置调试模式，调试模式下，找不到映射时将抛出异常而不是返回默认值 + * + * @param debugging true 为启用调试模式 + */ public void setDebugging(boolean debugging) { isDebugging = debugging; } + /** + * 获取文本 + * + * @param key 键 + * @param def 默认值（没有找到映射值时） + * @return 获取结果 + */ @Override public String text(String key, String def) { String result = text(key); return result.equals(key) ? def : result; } + /** + * 插入参数获取文本，使用 ${key} 格式进行占位符替换 + * + * @param key 键 + * @param args 参数映射表 + * @return 替换占位符后的文本 + */ @Override public String textArgs(String key, Map args) { return INTERPOLATOR.inject(text(key), args); diff --git a/src/main/java/com/imyeyu/lang/mapper/FileLanguageMap.java b/src/main/java/com/imyeyu/lang/mapper/FileLanguageMap.java index 20fad94..748615f 100644 --- a/src/main/java/com/imyeyu/lang/mapper/FileLanguageMap.java +++ b/src/main/java/com/imyeyu/lang/mapper/FileLanguageMap.java @@ -8,6 +8,8 @@ import java.io.InputStreamReader; import java.util.Properties; /** + * 文件语言映射 + * * @author 夜雨 * @version 2024-04-09 01:00 */ @@ -22,6 +24,11 @@ public class FileLanguageMap extends PropertiesLanguageMap { super(language); } + /** + * 加载资源文件，格式化 % 为 {@link Language.Enum#toString()}，示例：lang/app_%s.lang + * + * @param path 路径 + */ public void load(String path) { try { InputStream is = IO.getInputStream(path.formatted(language.toString())); diff --git a/src/main/java/com/imyeyu/lang/mapper/LanguageMap.java b/src/main/java/com/imyeyu/lang/mapper/LanguageMap.java index b635093..a4a73f8 100644 --- a/src/main/java/com/imyeyu/lang/mapper/LanguageMap.java +++ b/src/main/java/com/imyeyu/lang/mapper/LanguageMap.java @@ -10,13 +10,20 @@ import java.util.LinkedHashMap; import java.util.Map; /** + * 基于内存的语言映射实现 + *

+ * 使用 HashMap 存储语言映射关系，支持二次映射、模糊匹配等功能 + *

+ * * @author 夜雨 * @version 2024-04-03 10:11 */ public class LanguageMap extends AbstractLanguageMapper { + /** 语言键值映射表 */ protected final Map map; + // 初始化字符串插值器过滤器，支持 @key 格式的语言映射引用 { INTERPOLATOR.putFilter("lang", value -> { if (value.startsWith("@")) { @@ -36,15 +43,35 @@ public class LanguageMap extends AbstractLanguageMapper { this.map = new HashMap<>(); } + /** + * 合并另一个语言映射表 + *

+ * 将另一个映射表的所有键值对合并到当前映射表中，如果存在相同键则覆盖 + *

+ * + * @param map 要合并的语言映射表 + */ public void union(LanguageMap map) { this.map.putAll(map.map); } + /** + * 添加语言映射 + * + * @param key 键 + * @param value 值 + */ @Override public void add(String key, String value) { map.put(key, value); } + /** + * 检查是否存在指定键的映射 + * + * @param key 键 + * @return true 为存在 + */ @Override public boolean has(String key) { return map.containsKey(key); diff --git a/src/main/java/com/imyeyu/lang/mapper/PropertiesLanguageMap.java b/src/main/java/com/imyeyu/lang/mapper/PropertiesLanguageMap.java index f5d124b..b7aa67c 100644 --- a/src/main/java/com/imyeyu/lang/mapper/PropertiesLanguageMap.java +++ b/src/main/java/com/imyeyu/lang/mapper/PropertiesLanguageMap.java @@ -6,6 +6,8 @@ import java.util.HashMap; import java.util.Properties; /** + * 基于 Properties 的语言映射实现 + * * @author 夜雨 * @version 2024-04-09 00:50 */ @@ -20,6 +22,11 @@ public class PropertiesLanguageMap extends LanguageMap { super(language); } + /** + * 从 Properties 对象加载语言映射数据 + * + * @param properties 属性对象 + */ @SuppressWarnings({"unchecked", "rawtypes"}) public void load(Properties properties) { map.putAll(new HashMap(properties)); diff --git a/src/main/java/com/imyeyu/lang/mapper/ResourcesLanguageMap.java b/src/main/java/com/imyeyu/lang/mapper/ResourcesLanguageMap.java index f1eef44..2daf377 100644 --- a/src/main/java/com/imyeyu/lang/mapper/ResourcesLanguageMap.java +++ b/src/main/java/com/imyeyu/lang/mapper/ResourcesLanguageMap.java @@ -9,10 +9,13 @@ import java.io.InputStreamReader; import java.util.Properties; /** + * 资源文件语言映射 + * * @author 夜雨 * @version 2024-04-09 00:55 */ public class ResourcesLanguageMap extends PropertiesLanguageMap { + /** * 默认构造 * @@ -22,6 +25,11 @@ public class ResourcesLanguageMap extends PropertiesLanguageMap { super(language); } + /** + * 加载资源文件，格式化 % 为 {@link Language.Enum#toString()}，示例：lang/app_%s.lang + * + * @param path 路径 + */ public void load(String path) { try { InputStream is = IO.resourceToInputStream(getClass(), path.formatted(language.toString())); diff --git a/src/main/java/com/imyeyu/lang/multi/FileMultilingual.java b/src/main/java/com/imyeyu/lang/multi/FileMultilingual.java index 8aefaa0..486a9c1 100644 --- a/src/main/java/com/imyeyu/lang/multi/FileMultilingual.java +++ b/src/main/java/com/imyeyu/lang/multi/FileMultilingual.java @@ -6,11 +6,31 @@ import com.imyeyu.lang.mapper.FileLanguageMap; import com.imyeyu.lang.mapper.LanguageMap; /** + * 文件多语言实例，从文件系统加载多语言配置文件 + * * @author 夜雨 * @version 2024-04-09 01:06 */ public class FileMultilingual extends Multilingual { + /** + * 构造并批量加载所有支持的语言文件 + * + * @param path 文件路径模板，使用 %s 作为语言代码占位符，例如：lang/app_%s.lang + */ + public FileMultilingual(String path) { + addAll(path); + } + + /** + * 批量加载所有支持的语言文件 + *

+ * 遍历 {@link Language.Enum} 中定义的所有语言，为每种语言创建对应的映射器并加载文件。 + * 如果已存在相同语言的映射器，则合并映射数据 + *

+ * + * @param path 文件路径模板，使用 %s 作为语言代码占位符，例如：lang/app_%s.lang + */ public void addAll(String path) { Language.Enum[] values = Language.Enum.values(); for (int i = 0; i < values.length; i++) { diff --git a/src/main/java/com/imyeyu/lang/multi/Multilingual.java b/src/main/java/com/imyeyu/lang/multi/Multilingual.java index a8c340d..d0948ba 100644 --- a/src/main/java/com/imyeyu/lang/multi/Multilingual.java +++ b/src/main/java/com/imyeyu/lang/multi/Multilingual.java @@ -42,14 +42,24 @@ import java.util.Objects; */ public class Multilingual implements LanguageMapping { + /** 多语言映射表，存储各语言对应的映射器 */ protected final Map multilingualMap; + + /** 激活语言更新回调列表 */ protected final List> updateActiveListeners; /** 当前激活语言 */ protected Language.Enum activated; + /** 是否启用调试模式 */ protected boolean isDebugging = false; + /** + * 默认构造 + *

+ * 根据系统默认 Locale 初始化激活语言，如果无法识别则默认为中文 + *

+ */ public Multilingual() { multilingualMap = new HashMap<>(); updateActiveListeners = new ArrayList<>(); @@ -61,6 +71,12 @@ public class Multilingual implements LanguageMapping { } } + /** + * 添加语言映射器 + * + * @param language 语言 + * @param mapper 语言映射器 + */ public void add(Language.Enum language, AbstractLanguageMapper mapper) { mapper.setDebugging(isDebugging); multilingualMap.put(language, mapper); @@ -110,10 +126,23 @@ public class Multilingual implements LanguageMapping { } } + /** + * 获取当前激活的语言 + * + * @return 当前激活语言 + */ public Language.Enum getActivated() { return activated; } + /** + * 设置调试模式 + *

+ * 同时会将所有已加载的语言映射器设置为调试模式 + *

+ * + * @param debugging true 为启用调试模式 + */ public void setDebugging(boolean debugging) { isDebugging = debugging; for (Map.Entry item : multilingualMap.entrySet()) { @@ -145,6 +174,12 @@ public class Multilingual implements LanguageMapping { return multilingualMap.get(lang); } + /** + * 向当前激活语言的映射表添加键值对 + * + * @param key 键 + * @param value 值 + */ @Override public void add(String key, String value) { multilingualMap.get(getActivated()).add(key, value); diff --git a/src/main/java/com/imyeyu/lang/multi/ResourcesMultilingual.java b/src/main/java/com/imyeyu/lang/multi/ResourcesMultilingual.java index dd42ec5..60273c5 100644 --- a/src/main/java/com/imyeyu/lang/multi/ResourcesMultilingual.java +++ b/src/main/java/com/imyeyu/lang/multi/ResourcesMultilingual.java @@ -6,11 +6,34 @@ import com.imyeyu.lang.mapper.LanguageMap; import com.imyeyu.lang.mapper.ResourcesLanguageMap; /** + * 资源文件多语言实例 + *

+ * 从 classpath 资源文件加载多语言配置 + *

+ * * @author 夜雨 * @version 2024-04-09 01:03 */ public class ResourcesMultilingual extends Multilingual { + /** + * 构造并批量加载所有支持的语言资源文件 + * + * @param path 资源文件路径模板，使用 %s 作为语言代码占位符，例如：lang/app_%s.lang + */ + public ResourcesMultilingual(String path) { + addAll(path); + } + + /** + * 批量加载所有支持的语言资源文件 + *

+ * 遍历 {@link Language.Enum} 中定义的所有语言，为每种语言创建对应的映射器并从 classpath 加载资源。 + * 如果已存在相同语言的映射器，则合并映射数据 + *

+ * + * @param path 资源文件路径模板，使用 %s 作为语言代码占位符，例如：lang/app_%s.lang + */ public void addAll(String path) { Language.Enum[] values = Language.Enum.values(); for (int i = 0; i < values.length; i++) {