IDEA编写和查看函数的功能注释

使用方法

假设用户编写了如下函数

@Override  
public String savecode(String email) {  
    // 生成验证码  
    String code = generateCode();  
    // 存储到Redis  
    redisStringServer.set(  
            "email:code:"+email,  
            code,  
            Duration.ofMinutes(5) //ttl为5,5分钟内有效  
    );  
    return code;  
}

只要在函数上添加

/**
 * Javadoc 注释
 */

javadoc的注释，即可利用idea的工具便捷查看该函数说明
如：

/**  
 * * 生成验证码并将验证码设置TTL存活时长后保存到redis中  
 * @param email 生成对应用户邮箱的专属验证码  
 * @return 返回生成的验证码，仅用于发送邮件，不可用于验证身份  
 */  
@Override  
public String savecode(String email) {  
    // 生成验证码  
    String code = generateCode();  
    // 存储到Redis  
    redisStringServer.set(  
            "email:code:"+email,  
            code,  
            Duration.ofMinutes(5) //ttl为5,5分钟内有效  
    );  
    return code;  
}

如上，鼠标选停在引用函数的地方即可看到该函数的信息。

什么是 javadoc？

javadoc 是 JDK 自带的文档生成工具。

安装java时，会有这些工具

工具	作用
javac	编译 Java 源码
java	启动 JVM 运行程序
javap	反编译 .class 查看字节码
jar	打包 JAR 文件
javadoc	生成文档

它的作用是：

读取 Java 源代码中的注释（Javadoc 注释），生成一套 HTML API 文档。

执行：

javadoc UserService.java

会生成类似下面的文件：

doc/
├── index.html
├── UserService.html
├── package-summary.html
├── allclasses-index.html
└── ...

打开：

index.html

浏览器中就能看到类似 Oracle 官方 API 文档的页面。

注：现代的IDE（如 IntelliJ IDEA）可以直接读取 Javadoc 注释，在鼠标悬停或代码补全时显示说明。

Javadoc 注释是什么？

Java 有三种注释：

// 单行注释

/* 多行注释 */

/**
 * Javadoc 注释
 */

只有第三种 /** ... */ 会被 javadoc 工具解析。

例如：

/**
 * 两数相加
 *
 * @param a 第一个数字
 * @param b 第二个数字
 * @return 相加后的结果
 */
public int add(int a, int b) {
    return a + b;
}

这里：

• @param 描述参数
• @return 描述返回值
• @throws 描述异常
• @author 作者
• @since 从哪个版本开始
• @see 关联其他类或方法