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 <noreply@anthropic.com>

.gitignore

@@ -1,3 +1,7 @@
+/.claude
+/CLAUDE.md
+/AGENTS.md
+
 target/
 !.mvn/wrapper/maven-wrapper.jar
 !**/src/main/**/target/

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<String, Object> args) {
 		return INTERPOLATOR.inject(text(key), args);

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()));

src/main/java/com/imyeyu/lang/mapper/LanguageMap.java

@@ -10,13 +10,20 @@ import java.util.LinkedHashMap;
 import java.util.Map;
 
 /**
+ * 基于内存的语言映射实现
+ * <p>
+ * 使用 HashMap 存储语言映射关系，支持二次映射、模糊匹配等功能
+ * </p>
+ *
  * @author 夜雨
  * @version 2024-04-03 10:11
  */
 public class LanguageMap extends AbstractLanguageMapper {
 
+	/** 语言键值映射表 */
 	protected final Map<String, String> map;
 
+	// 初始化字符串插值器过滤器，支持 @key 格式的语言映射引用
 	{
 		INTERPOLATOR.putFilter("lang", value -> {
 			if (value.startsWith("@")) {
@@ -36,15 +43,35 @@ public class LanguageMap extends AbstractLanguageMapper {
 		this.map = new HashMap<>();
 	}
 
+	/**
+	 * 合并另一个语言映射表
+	 * <p>
+	 * 将另一个映射表的所有键值对合并到当前映射表中，如果存在相同键则覆盖
+	 * </p>
+	 *
+	 * @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);

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));

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()));

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);
+	}
+
+	/**
+	 * 批量加载所有支持的语言文件
+	 * <p>
+	 * 遍历 {@link Language.Enum} 中定义的所有语言，为每种语言创建对应的映射器并加载文件。
+	 * 如果已存在相同语言的映射器，则合并映射数据
+	 * </p>
+	 *
+	 * @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++) {

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<Language.Enum, AbstractLanguageMapper> multilingualMap;
+
+	/** 激活语言更新回调列表 */
 	protected final List<CallbackArg<Language.Enum>> updateActiveListeners;
 
 	/** 当前激活语言 */
 	protected Language.Enum activated;
 
+	/** 是否启用调试模式 */
 	protected boolean isDebugging = false;
 
+	/**
+	 * 默认构造
+	 * <p>
+	 * 根据系统默认 Locale 初始化激活语言，如果无法识别则默认为中文
+	 * </p>
+	 */
 	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;
 	}
 
+	/**
+	 * 设置调试模式
+	 * <p>
+	 * 同时会将所有已加载的语言映射器设置为调试模式
+	 * </p>
+	 *
+	 * @param debugging true 为启用调试模式
+	 */
 	public void setDebugging(boolean debugging) {
 		isDebugging = debugging;
 		for (Map.Entry<Language.Enum, AbstractLanguageMapper> 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);

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;
 
 /**
+ * 资源文件多语言实例
+ * <p>
+ * 从 classpath 资源文件加载多语言配置
+ * </p>
+ *
  * @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);
+	}
+
+	/**
+	 * 批量加载所有支持的语言资源文件
+	 * <p>
+	 * 遍历 {@link Language.Enum} 中定义的所有语言，为每种语言创建对应的映射器并从 classpath 加载资源。
+	 * 如果已存在相同语言的映射器，则合并映射数据
+	 * </p>
+	 *
+	 * @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++) {