1. 概述
Javadoc 是一种从 Java 源代码生成 HTML 格式文档的工具。本文将重点探讨文档注释中的 @version 和 @since 这两个注解的使用方法。
2. @version 和 @since 的使用
本节将详细说明如何正确使用这两个注解。
2.1 @version
@version 注解的格式非常简单：
@version version-text
例如，用它标注 JDK 1.7：
/**
* @version JDK 1.7
*/
@version 有两种典型使用场景：
- 记录单个文件的版本
- 标记整个软件的版本
这两种场景存在明显差异：单个文件版本可能与软件版本不兼容，且不同文件的版本可能各不相同。那么该如何使用呢？
过去 Sun 公司用 @version 记录单个文件版本，建议使用 SCCS 字符串 %I%, %G%。SCCS 会在检出文件时将 %I% 替换为文件当前版本号，%G% 替换为日期（格式 mm/dd/yy），例如 1.39, 02/28/97。每次编辑并执行 delget（增量获取）操作时，%I% 会自动递增。
SCCS（Source Code Control System）是老古董级版本控制系统（IBM 文档参考）。
现在我们更倾向于用 @version 标记整个软件版本，这使得放在单个文件里的 @version 显得多余。这是否意味着单个文件版本不再重要？并非如此——现代版本控制系统（如 Git/SVN/CVS）有自己记录文件版本的方式，无需依赖 @version。
以 Oracle JDK 8 为例，查看 src.zip 会发现只有 java.awt.Color 类使用了 @version：
/**
* @version 10 Feb 1997
*/
可见用 @version 标记文件版本的做法正在淘汰。因此 Oracle 官方文档 建议用 @version 记录软件当前版本号。
2.2 @since
@since 注解的格式同样简单：
@since since-text
例如，标注 JDK 1.7 引入的特性：
/**
* @since JDK 1.7
*/
@since 用于描述变更或特性首次出现的版本，同样指软件发布版本而非文件版本。Oracle 官方文档 给出详细使用指南：
- 引入新包时，应在包描述和每个类中添加
@since - 添加新类/接口时，只需在类描述中添加（不必在成员中）
- 向现有类添加新成员时，只需在新成员中添加
@since - 后续版本中将成员从 protected 改为 public 时，不应修改
@since
@since 能为用户提供重要提示：特定功能仅在特定版本后可用。查看 JDK 源码会发现大量使用案例，例如 java.lang.FunctionalInterface：
/**
* @since 1.8
*/
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
public @interface FunctionalInterface {}
这段代码明确表示 FunctionalInterface 仅在 JDK 8+ 可用。
3. @version 和 @since 的共同点
这两个注解存在几个关键相似点。
3.1 同属块标签
两者都属于块标签（Block Tags）。
文档注释的标签分两类：
- 块标签
- 行内标签
块标签格式为 @tag，必须出现在行首（忽略前导星号、空格和分隔符 /**）。例如：
/**
* Some description here.
*
* @version 1.2
* @since 1.1
*/
行内标签格式为 {@tag}，可出现在描述的任意位置。例如 {@link}：
/**
* We can use a {@link java.lang.StringBuilder} class here.
*/
3.2 都可重复使用
两者都允许多次使用。这个特性可能让人意外——一个类里出现多个 @version？但这是官方文档明确支持的：因为同一程序元素可能属于多个 API。
例如当同一类用于 ADK 和 JDK 不同版本时：
/**
* Some description here.
*
* @version ADK 1.6
* @version JDK 1.7
* @since ADK 1.3
* @since JDK 1.4
*/
生成的 HTML 文档中，Javadoc 工具会用逗号+空格分隔多个值：
ADK 1.6, JDK 1.7
ADK 1.3, JDK 1.4
4. @version 和 @since 的差异
4.1 内容是否变化
@version 内容持续变化，@since 内容稳定。随着软件迭代，版本号会不断更新；而 @since 标记的是历史时间点，一旦确定就不再修改。
4.2 使用范围差异
两者的适用范围不同：
@version：概览页、包、类、接口@since：概览页、包、类、接口、字段、构造方法、普通方法
@since 适用范围更广，可用于任何文档注释，而 @version 无法用于字段、构造方法和方法。
4.3 默认显示行为
两者在生成 HTML 时的默认行为不同：
@version默认不显示@since默认显示
想显示版本信息需加 -version 选项：
javadoc -version -d docs/ src/*.java
想隐藏 @since 信息需加 -nosince 选项：
javadoc -nosince -d docs/ src/*.java
5. 总结
本文详细讲解了 @version 和 @since 的正确使用方式，并对比了它们的异同。简单来说：
@version用于记录软件当前版本号@since用于标记特性或变更首次出现的版本
合理使用这两个注解，能让你的 API 文档更专业、更易维护。实际开发中建议优先使用 @since，而 @version 则根据团队规范谨慎使用——毕竟现代版本控制系统已经能更好地管理版本信息了。