Javadoc: @version and @since – Javadoc @version和@since

最后修改: 2021年 9月 5日

中文/混合/英文(键盘快捷键：t)

1. Overview

1.概述

Javadoc is a way to generate documentation in HTML format from Java source code.

Javadoc是一种从Java源代码生成HTML格式文档的方法。

In this tutorial, we’ll focus on the @version and @since tags in doc comments.

在本教程中，我们将重点讨论文档注释中的@version和@since标签。

2. Usage of @version and @since

<span data-sheets-userformat='{“2″:2819,”3”:{“1″:0},”4”:{“1″:2,”2″:16777215},”11″:4,”12″:0,”14”:{“1″:2,”2”:3355443}}’ data-sheets-value='{“1″:2,”2”:”2.2.<em>@version和@since的使用情况

In this section, we’ll talk about how to use the @version and @since tags properly.

在本节中，我们将讨论如何正确使用@version和@since标签。

2.1. @version

2.1. @version

The format of the @version tag is straightforward:

@version标签的格式是直接的。

@version  version-text

For example, we can use it to indicate JDK 1.7:

例如，我们可以用它来表示JDK 1.7。

/**
 * @version JDK 1.7
 */

When we use the @version tag, it has two different usage scenarios:

当我们使用@version标签时，它有两种不同的使用场景。

  • Record the version of a single file
  • Mark the version of the whole software

Obviously, we can see that there is a discrepancy between these two scenarios. That’s because the version of a single file may not be compatible with the version of the software. Besides, different files may have different file versions. So, how should we use the @version tag?

很明显，我们可以看到，这两种情况之间存在差异。这是因为单个文件的版本可能与软件的版本不兼容。此外，不同的文件可能有不同的文件版本。那么，我们应该如何使用@version标签？

In the past, Sun used the @version tag to record the version of a single file. And it recommended that the @version tag used the SCCS string “%I%, %G%“. Then, the SCCS would replace “%I%” with the current version of the file and “%G%” with the date “mm/dd/yy” when we check the file out. For example, it would look like “1.39, 02/28/97” (mm/dd/yy).  Furthermore, %I% gets incremented each time we edit and delget(delta + get) a file.

过去，Sun使用@version标签来记录单个文件的版本。并且建议@version标签使用SCCS字符串”%I%, %G%“。然后，SCCS将用文件的当前版本替换”%I%“，当我们检出文件时，”%G%“替换为日期 “mm/dd/yy”。例如，它将看起来像 “1.39, 02/28/97″（mm/dd/yy）。 此外，每次我们编辑和删除（delta + get）一个文件时，%I%会被递增。

The SCCS is also known as Source Code Control System. If we want to know more about SCCS Command, we can refer to it here. In addition, SCCS is an old-fashioned source-code version control system.

SCCS也被称为源代码控制系统。如果我们想了解更多关于SCCS命令的信息，我们可以参考这里。此外，SCCS是一个老式的源代码版本控制系统。

At present, we tend to use the @version tag to indicate the version of the whole software. In light of this, it makes the @version tag placed in a single file unnecessarily.

目前，我们倾向于使用@version标签来表示整个软件的版本。鉴于此，它使@version标签不必要地放在一个文件中。

Does it mean that the version of a single file is no longer important? That’s not actually true. Now, we have modernized version control software, such as Git, SVN, CVS, and so on. Each version control software has its unique way of recording the version of every single file and doesn’t need to rely on the @version tag.

这是否意味着单个文件的版本不再重要了？实际上不是这样的。现在，我们有现代化的版本控制软件，如Git、SVN、CVS等等。每个版本控制软件都有其独特的方式来记录每一个文件的版本，不需要依赖@version标签。

Let’s take Oracle JDK 8 as an example. If we look at the source code in the src.zip file, we may find only the java.awt.Color class has a @version tag:

让我们以Oracle JDK 8为例。如果我们看一下src.zip文件中的源代码，我们可能会发现只有java.awt.Color类有一个@version标签。

/**
 * @version     10 Feb 1997
 */

So, we may infer that using the @version tag to indicate the version of a single file is fading. Thus, the Oracle doc suggests that we use the @version tag to record the current version number of the software.

因此，我们可以推断，使用@version标签来表示单个文件的版本正在逐渐消失。因此，Oracle doc建议我们使用@version标签来记录软件的当前版本号。

2.2. @since

2.2.@since

The format of the @since tag is quite simple:

@since标签的格式非常简单。

@since  since-text

For example, we can use it to mark a feature introduced in JDK 1.7:

例如，我们可以用它来标记JDK 1.7中引入的一个特性。

/**
 * @since JDK 1.7
 */

In short, we use the @since tag to describe when a change or feature has first existed. Similarly, it uses the release version of the whole software, not the version of a single file. The Oracle doc gives us some detailed instructions on how to use the @since tag:

简而言之，我们使用@since标签来描述一个变化或功能首次存在的时间。同样地，它使用整个软件的发布版本，而不是单个文件的版本。Oracle doc给了我们一些关于如何使用@since标签的详细说明。

  • When introducing a new package, we should specify an @since tag in the package description and each of its classes.
  • When adding a new class or interface, we should specify one @since tag in the class description, not in the description of class members.
  • If we add new members to an existing class, we should only specify @since tags to members newly added, not in the class description.
  • If we change a class member from protected to public in a later release, we shouldn’t change the @since tag.

Sometimes, the @since tag is rather important because it provides a vital hint that software users should only expect a specific feature after some certain release version.

有时，@since标签相当重要，因为它提供了一个重要的提示，即软件用户应该只在某个特定的发行版本之后期待一个特定的功能。

If we look at the src.zip file again, we may find many @since tag usages. Let’s take the java.lang.FunctionalInterface class as an example:

如果我们再看一下src.zip文件，我们可能会发现许多@since标签的使用。让我们以java.lang.FunctionalInterface类为例。

/**
 * @since 1.8
 */
@Documented
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
public @interface FunctionalInterface {}

From this code snippet, we can learn that the FunctionalInterface class is only available in JDK 8 and above.

从这个代码片段中，我们可以了解到，FunctionalInterface类只在JDK 8及以上版本中可用。

3. Similarities Between @version and @since

3.@version和@since之间的相似性

In this section, let’s look at the similarities between the @version and @since tags.

在本节中，让我们看看@version和@since标签之间的相似性。

3.1. Both Belong To Block Tags

3.1.都属于块状标签

Firstly, both @version and @since belong to block tags.

首先，@version和@since都属于块标签。

In doc comments, tags can be categorized into two types:

在文档评论中，标签可以分为两种类型。

  • Block tags
  • Inline tags

A block tag has a form of @tag. And it should appear at the beginning of a line, ignoring leading asterisks, white space, and separator (/**). For example, we can use @version and @since in the tag section:

一个块状标签的形式是@tag。而且它应该出现在一行的开头，忽略前面的星号、空白和分隔符（/**）。例如，我们可以在标签部分使用@version和@since。

/**
 * Some description here.
 * 
 * @version 1.2
 * @since 1.1
 */

However, an inline tag has the form of {@tag}. And it can exist anywhere in descriptions or comments. For example, if we have a {@link} tag, we can use it in the description:

然而，一个内联标签的形式是{@tag}。而且它可以存在于描述或评论的任何地方。例如，如果我们有一个{@link}标签，我们可以在描述中使用它。

/**
 * We can use a {@link java.lang.StringBuilder} class here.
 */

3.2. Both Can Be Used Multiple Times

3.2.都可以多次使用

Secondly, both @version and @since can be used multiple times. At first, we may be shocked by this usage. Then, we may wonder how can the @version tag appear multiple times in a single class. But it is true, and it is documented here. And it explains that we can use the same program element in more than one API. So, we can attach various versions with the same program element.

其次，@version和@since都可以多次使用。一开始，我们可能会对这种用法感到震惊。然后，我们可能会想，@version标签怎么可能在一个类中出现多次。但这是真的，而且它被记录在这里。而且它解释了我们可以在多个API中使用同一个程序元素。所以，我们可以用同一个程序元素附加各种版本。

For example, if we use the same class or interface in different versions of ADK and JDK, we can provide different @version and @since messages:

例如，如果我们在不同版本的ADK和JDK中使用同一个类或接口，我们可以提供不同的@version和@since信息。

/**
 * Some description here.
 *
 * @version ADK 1.6
 * @version JDK 1.7
 * @since ADK 1.3
 * @since JDK 1.4
 */

In the generated HTML pages, the Javadoc tool will insert a comma (,) and space between names. Thus, the version text looks like this:

在生成的HTML页面中，Javadoc工具会在名字之间插入逗号（,）和空格。因此，版本文本看起来像这样。

ADK 1.6, JDK 1.7

And, the since text looks like:

而且，自文本看起来像。

ADK 1.3, JDK 1.4

4. Differences Between @version And @since

4.@version和@since之间的差异

In this section, let’s look at the differences between the @version and @since tags.

在本节中，让我们看看@version和@since标签的区别。

4.1. Whether Their Content Change

4.1.其内容是否改变

The @version text is constantly changing, and the @since text is stable. As time goes by, the software is constantly evolving. New features will join, so its version will continue to change. However, the @since tag only identifies a time point in the past at which new changes or features came into existence.

@version文本是不断变化的，@since文本是稳定的。随着时间的推移，软件在不断发展。新的功能会加入，所以它的版本会不断变化。然而，@since标签只确定了过去的一个时间点，在这个时间点上出现了新的变化或功能。

4.2. Where They Can Be Used

4.2.可使用的地方

These two tags have slightly different usages:

这两个标签的用途略有不同。

  • @version: overview, package, class, interface
  • @since: overview, package, class, interface, field, constructor, method

The @since tag has a wider range of usages, and it is valid in any doc comment. In contrast, the @version tag has a narrower range of usages, and we can’t use it in fields, constructors, or methods.

@since标签的使用范围更广，它在任何文档注释中都有效。相比之下，@version标签的使用范围较窄，我们不能在字段、构造函数或方法中使用它。

4.3. Whether They Appear by Default

4.3.它们是否以默认方式出现

These two tags have different behaviors in the generated HTML pages by default:

这两个标签在默认情况下，在生成的HTML页面中有不同的行为。

  • The @version text doesn’t show by default
  • The @since text does appear by default

If we want to include “version text” in generated docs, we can use -version option:

如果我们想在生成的文档中包括 “版本文本”，我们可以使用-version选项。

javadoc -version -d docs/ src/*.java

Likewise, if we want to omit “since text” in generated docs, we can use -nosince option:

同样，如果我们想在生成的文档中省略 “自文本”，我们可以使用-nosince选项。

javadoc -nosince -d docs/ src/*.java

5. Conclusion

5.总结

In this tutorial, we first talked about how to use the @version and @since tags correctly. Then we described the similarities and differences between them. In short, the @version tag holds the current version number of the software, and the @since tag describes when a change or feature has first existed.

在本教程中，我们首先谈到了如何正确使用@version和@since标签。然后我们描述了它们之间的异同。简而言之，@version标签持有软件的当前版本号，而@since标签则描述了某项更改或功能首次出现的时间。