Javadoc: @version and @since

1. Overview

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

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

2. Usage Of @version And @since

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

2.1. @version

The format of the @version tag is straightforward:

@version  version-text

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

/**
 * @version JDK 1.7
 */

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

• 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?

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.

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.

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.

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.

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:

/**
 * @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.

2.2. @since

The format of the @since tag is quite simple:

@since  since-text

For example, we can use it to mark a feature introduced in 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:

• 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.

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:

/**
 * @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.

3. Similarities Between @version And @since

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

3.1. Both Belong To Block Tags

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

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:

/**
 * 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:

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

3.2. Both Can Be Used Multiple Times

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.

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:

/**
 * 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:

ADK 1.6, JDK 1.7

And, the since text looks like:

ADK 1.3, JDK 1.4

4. Differences Between @version And @since

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

4.1. Whether Their Content Change

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.

4.2. Where They Can Be Used

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.

4.3. Whether They Appear By Default

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

• 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:

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

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

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

5. Conclusion

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.