javadoc：@version 和@since
声明：本页面是StackOverFlow热门问题的中英对照翻译，遵循CC BY-SA 4.0协议，如果您需要使用它，必须同样遵循CC BY-SA许可，注明原文地址和作者信息，同时你必须将它归于原作者（不是我）：StackOverFlow
原文地址: http://stackoverflow.com/questions/578363/
Warning: these are provided under cc-by-sa 4.0 license. You are free to use/share it, But you must attribute it to the original authors (not me):
StackOverFlow
javadoc: @version and @since
提问by
Is there a reason to include both @versionand @sinceas part of a class?
是否有一个理由，包括@version和@since作为一类的一部分？
They seem to be mutually exclusive.
它们似乎是相互排斥的。
Also, what does %I%and %G%mean, and how to set/use them?
此外，这是什么%I%和%G%意味着，以及如何设置/使用它们？
@version %I%, %G%
Thanks
谢谢
采纳答案by dhable
The @versiontag should be the current version of the release or file in question. The %I%, %G%syntax are macros that the source control software would replace with the current version of the file and the date when the file is checked out.
该@version标签应该是有问题的释放或文件的最新版本。的%I%，%G%语法是宏的源代码控制软件将与文件的当前版本和日期替换文件时签出。
The @sincetag should be used to define which version you added the method, class, etc. This is your hint to other developers that they should only expect the method when they run against a particular version of the package. I would consider these uber-important parts of the documentation if you're shipping your code as a library intended for someone else to use.
该@since标记应该用于定义您添加了哪个版本的方法、类等。这是您向其他开发人员的提示，他们应该只在针对特定版本的包运行时才期望该方法。如果您将代码作为供其他人使用的库发送，我会考虑文档中这些非常重要的部分。
回答by Yuval Adam
I don't see how they are mutually exclusive. One is used to define version, and the other is used for describing since when the method is there. For example:
我看不出它们是如何相互排斥的。一个用于定义版本，另一个用于描述方法何时存在。例如：
/**
* Does Whatever
* @version 1.2.3
* @since 1.2.0
*
*/
public void myMethod() {
// .......
}
Regarding the characters you mentioned, they seem proprietary, and in any case I have no clue what they mean.
关于你提到的字符，它们似乎是专有的，无论如何我不知道它们的意思。
回答by zg_spring
@versionwill be record every edit.[1.3.21]
@version将记录每次编辑。 [1.3.21]
@sinceis mean since which release version will be support this interface or etc.[1.3]
Yuval Adam is interesting, but this is not the standard, java doc 's purpose is everyone can understand.
@since是指哪个版本会支持这个接口等等。[1.3] Yuval Adam 很有趣，但这不是标准，java doc 的目的是每个人都能理解的。
回答by ifeegoo
Explained well in an article from Oracle, How to Write Doc Comments for the Javadoc Tool.
Oracle 的一篇文章How to Write Doc Comments for the Javadoc Tool 中对此进行了很好的解释。
@version
@version
…classes and interfaces only.
At Java Software, we use @version for the SCCS version. See "man sccs-get" for details. The consensus seems to be the following:
%I% gets incremented each time you edit and delget a file
%G% is the date mm/dd/yy
When you create a file, %I% is set to 1.1. When you edit and delget it, it increments to 1.2.
Some developers omit the date %G% (and have been doing so) if they find it too confusing -- for example, 3/4/96, which %G% would produce for March 4th, would be interpreted by those outside the United States to mean the 3rd of April. Some developers include the time %U% only if they want finer resolution (due to multiple check-ins in a day).
The clearest numeric date format would be to have the date formatted with the year first, something like yyyy-mm-dd, as proposed in ISO 8601 and elsewhere (such as http://www.cl.cam.ac.uk/~mgk25/iso-time.html), but that enhancement would need to come from SCCS.
...仅限类和接口。
在 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
@since
Specify the product version when the Java name was added to the API specification (if different from the implementation). For example, if a package, class, interface or member was added to the Java 2 Platform, Standard Edition, API Specification at version 1.2, use:
将 Java 名称添加到 API 规范时指定产品版本（如果与实现不同）。例如，如果将包、类、接口或成员添加到 Java 2 平台标准版 API 规范 1.2 版，请使用：
/**
* @since 1.2
*/
The Javadoc standard doclet displays a "Since" subheading with the string argument as its text. This subheading appears in the generated text only in the place corresponding to where the @since tag appears in the source doc comments (The Javadoc tool does not proliferate it down the hierarchy).
(The convention once was " @since JDK1.2" but because this is a specification of the Java Platform, not particular to the Oracle JDK or SDK, we have dropped "JDK".)
When a package is introduced, specify an @since tag in its package description and each of its classes. (Adding @since tags to each class is technically not needed, but is our convention, as enables greater visibility in the source code.) In the absence of overriding tags, the value of the @since tag applies to each of the package's classes and members.
When a class (or interface) is introduced, specify one @since tag in its class description and no @since tags in the members. Add an @since tag only to members added in a later version than the class. This minimizes the number of @since tags.
If a member changes from protected to public in a later release, the @since tag would not change, even though it is now usable by any caller, not just subclassers.
Javadoc 标准 doclet 显示一个“Since”副标题，并以字符串参数作为其文本。此副标题仅出现在生成的文本中与 @since 标记出现在源文档注释中的位置相对应的位置（Javadoc 工具不会在层次结构中向下扩展）。
（惯例曾经是“@since JDK1.2”，但因为这是 Java 平台的规范，而不是 Oracle JDK 或 SDK 的规范，我们删除了“JDK”。）
当一个包被引入时，在它的包描述和它的每个类中指定一个@since 标签。（在技术上不需要为每个类添加 @since 标签，但这是我们的惯例，因为可以在源代码中提供更大的可见性。）在没有覆盖标签的情况下，@since 标签的值适用于包的每个类和成员。
当一个类（或接口）被引入时，在它的类描述中指定一个@since 标签，并且在成员中没有@since 标签。仅将@since 标记添加到在类的更新版本中添加的成员。这最大限度地减少了@since 标签的数量。
如果一个成员在以后的版本中从 protected 变为 public，@since 标签不会改变，即使它现在可供任何调用者使用，而不仅仅是子类。
