javadoc:@version和@since

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

它们似乎是相互排斥的.

此外,这是什么%I%和%G% 意味着,以及如何设置/使用它们？

 @version %I%, %G% 

谢谢

1> dhable..：

---

该@version标签应该是有问题的释放或文件的最新版本.的%I%,%G%语法是宏当文件被签出源代码控制软件将与文件的当前版本和日期替换.

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

---

要添加Rob的评论,我通常会在查看JDK文档时发现它们很有用.有一段时间我是一个愚蠢的年轻开发人员,并在部署使用1.3时在Windows上使用JDK1.4开发我的项目.我花了部署的早晨试图修复丢失方法的异常.

2> ifeegoo..：

---

在Oracle的一篇文章中解释得很清楚,如何为Javadoc工具编写文档注释.

@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规范时指定产品版本(如果与实现不同).例如,如果将包,类,接口或成员添加到版本1.2的Java 2平台标准版API规范中,请使用:

/**
 * @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标记不会更改,即使现在任何调用者都可以使用它,而不仅仅是子类.

3> Yuval Adam..：

---

我不知道它们是如何相互排斥的.一个用于定义版本,另一个用于描述,因为方法存在时.例如:

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

关于你提到的人物,他们似乎是专有的,无论如何我不知道他们的意思.

---

首先,@ since表示版本#而不是日期,因为它是可用的版本.如果我错在这里请纠正.谢谢

---

谢谢,有趣,但java说不同.您是在建议反对Java的学说的常见做法吗？

---

没错,`@ Since`似乎定义了[版本号](http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#@since).请回顾一下这个答案.