` 标签分隔段落： ```java /** * 第一段内容 * *
第二段内容 * *
第三段内容 */ ``` ## 类注释 ### 基本结构 ```java /** * 类描述 * *
详细说明 * * @author 作者名 * @since 版本号或日期 * @version 版本号（可选） */ public class MyClass { } ``` ### 必需标签 - `@author`: 作者信息 - `@since`: 首次引入的版本或日期 ### 可选标签 - `@version`: 版本号 - `@see`: 相关类或方法的引用 - `@deprecated`: 标记为已废弃 ### 示例 ```java /** * 用户管理服务 * *
提供用户相关的业务逻辑处理，包括用户的创建、查询、更新和删除操作。 * 本服务遵循领域驱动设计（DDD）原则，封装用户领域的核心业务逻辑。 * * @author System * @since 1.0.0 * @version 1.0.0 */ public class UserService { } ``` ## 方法注释 ### 基本结构 ```java /** * 方法描述 * *
详细说明（可选） * * @param 参数名 参数说明 * @return 返回值说明 * @throws 异常类型 异常说明 */ public ReturnType methodName(ParamType param) { } ``` ### 必需标签 - `@param`: 每个参数都需要一个 @param 标签 - `@return`: 如果方法有返回值，必须包含 @return 标签 - `@throws`: 如果方法可能抛出异常，必须包含 @throws 标签 ### 示例 ```java /** * 根据用户 ID 查询用户信息 * *
根据提供的用户 ID 从数据库查询对应的用户详细信息。 * 如果用户不存在，将抛出 ResourceNotFoundException 异常。 * * @param id 用户唯一标识符，不能为 null * @return 用户信息 DTO，如果用户不存在则返回 null * @throws ResourceNotFoundException 当用户不存在时抛出 * @throws IllegalArgumentException 当 id 为 null 时抛出 */ public UserDTO findById(Long id) { // 实现代码 } ``` ## 字段注释 ### 基本结构 ```java /** * 字段描述 * *
详细说明（可选） */ private FieldType fieldName; ``` ### 示例 ```java /** * 用户数据访问对象 * *
用于执行用户相关的数据库操作，由 Spring 容器注入
*/
private final UserMapper userMapper;
```
## 常用标签
### @param
用于描述方法参数：
```java
/**
* @param username 用户名，长度 3-20 个字符
* @param password 密码，长度至少 8 个字符
*/
public void login(String username, String password) {
}
```
### @return
用于描述返回值：
```java
/**
* @return 用户信息列表，如果不存在则返回空列表
*/
public List 主要功能：
* 处理流程：
* 使用示例：
* 使用 {@code UserService} 处理用户相关业务
*/
```
### 链接
```java
/**
* 参考 {@link UserService#findById(Long)}
*/
```
## 最佳实践
1. **简洁明了**：注释应该清晰、简洁，避免冗余
2. **完整准确**：确保注释准确反映代码的实际行为
3. **及时更新**：代码修改时同步更新注释
4. **使用标准格式**：遵循 JavaDoc 标准格式
5. **包含示例**：对于复杂方法，提供使用示例
6. **说明副作用**：如果方法有副作用，必须在注释中说明
## 常见错误
### 错误 1: 缺少 @param 标签
```java
// ❌ 错误
/**
* 创建用户
*/
public void createUser(String username) {
}
// ✅ 正确
/**
* 创建用户
*
* @param username 用户名
*/
public void createUser(String username) {
}
```
### 错误 2: 缺少 @return 标签
```java
// ❌ 错误
/**
* 查询用户
*/
public UserDTO findById(Long id) {
}
// ✅ 正确
/**
* 查询用户
*
* @param id 用户 ID
* @return 用户信息 DTO
*/
public UserDTO findById(Long id) {
}
```
### 错误 3: 注释与代码不一致
```java
// ❌ 错误：注释说返回 null，但实际抛出异常
/**
* @return 用户信息，如果不存在则返回 null
*/
public UserDTO findById(Long id) {
throw new ResourceNotFoundException();
}
// ✅ 正确
/**
* @param id 用户 ID
* @return 用户信息 DTO
* @throws ResourceNotFoundException 当用户不存在时抛出
*/
public UserDTO findById(Long id) {
throw new ResourceNotFoundException();
}
```
## 参考资源
- [Oracle JavaDoc Guide](https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html)
- [JavaDoc 规范](https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html)
*
*/
```
### 有序列表
```java
/**
*
*
*/
```
### 代码块
```java
/**
* {@code
* UserService service = new UserService();
* UserDTO user = service.findById(1L);
* }
*/
```
### 内联代码
```java
/**
*