java - javadoc：@version 和 @since

Question

是否有理由将两者都包括在内@version并@since作为课程的一部分？

它们似乎是相互排斥的。

另外，是什么意思，%I%以及%G% 如何设置/使用它们？

 @version %I%, %G%

Answer 1

@version标签应该是当前版本的发行版或相关文件。,语法是源代码管理软件将用文件的当前版本和文件签出日期替换的宏%I%。%G%

该@since标记应该用于定义您添加了方法、类等的哪个版本。这是您对其他开发人员的提示，他们应该只在针对特定版本的包运行时才期望该方法。如果您将代码作为供其他人使用的库提供，我会考虑文档中这些非常重要的部分。

Answer 2

在 Oracle 的一篇文章How to Write Doc Comments for the Javadoc Tool中有很好的解释。

@version

…仅限类和接口。

在 Java Software，我们使用@version 表示 SCCS 版本。有关详细信息，请参阅“man sccs-get”。共识似乎如下：

每次编辑和删除文件时，%I% 都会增加

%G% 是日期 mm/dd/yy

创建文件时，%I% 设置为 1.1。当您编辑和删除它时，它会增加到 1.2。

如果某些开发人员觉得 %G% 太混乱，他们会省略日期（并且一直这样做）——例如，3/4/96，%G% 将在 3 月 4 日生成，将由美国以外的人解释州意味着 4 月 3 日。一些开发人员仅在他们想要更精细的分辨率时才包含时间 %U%（由于一天内多次签入）。

最清晰的数字日期格式是将日期格式化为第一个年份，例如 yyyy-mm-dd，如 ISO 8601 和其他地方（例如http://www.cl.cam.ac.uk/~ mgk25/iso-time.html），但这种增强需要来自 SCCS。

@since

指定将 Java 名称添加到 API 规范时的产品版本（如果与实现不同）。例如，如果将包、类、接口或成员添加到 Java 2 Platform, Standard Edition, API Specification 1.2 版，请使用：

/**
 * @since 1.2
 */

Javadoc 标准 doclet 显示一个“Since”子标题，其中字符串参数作为其文本。此子标题仅出现在生成的文本中与源文档注释中 @since 标记出现的位置相对应的位置（Javadoc 工具不会将其沿层次结构扩展）。

（约定曾经是“@since JDK1.2”，但因为这是 Java 平台的规范，而不是特定于 Oracle JDK 或 SDK，所以我们删除了“JDK”。）

当一个包被引入时，在它的包描述和它的每个类中指定一个@since 标签。（在技术上不需要为每个类添加@since 标签，但这是我们的惯例，因为这样可以提高源代码的可见性。）在没有覆盖标签的情况下，@since 标签的值适用于每个包的类和成员。

引入类（或接口）时，在其类描述中指定一个@since 标签，在成员中不指定@since 标签。仅将@since 标记添加到在比类更高版本中添加的成员。这最大限度地减少了@since 标签的数量。

如果成员在以后的版本中从 protected 更改为 public，@since 标记不会更改，即使它现在可供任何调用者使用，而不仅仅是子类。

Answer 3

我看不出它们是如何相互排斥的。一个用于定义版本，另一个用于描述方法何时存在。例如：

/**
 * Does Whatever
 * @version 1.2.3
 * @since 1.2.0
 *
 */
public void myMethod() {
    // .......
}

关于你提到的字符，它们似乎是专有的，无论如何我都不知道它们是什么意思。

Answer 4

@version将记录每次编辑。[1.3.21]

@since意思是因为哪个发行版本会支持这个接口等等。[1.3] Yuval Adam 很有趣，但这不是标准，java doc 的目的是每个人都能理解。