Перейти к основному содержимому

Javadoc: @version и @since

· 7 мин. чтения

1. Обзор​

Javadoc — это способ создания документации в формате HTML из исходного кода Java.

В этом руководстве мы сосредоточимся на тегах @version и @since в комментариях к документам.

2. Использование @version и @since​

В этом разделе мы поговорим о том, как правильно использовать теги @version и @since .

2.1. @версия​

Формат тега @version прост:

@version  version-text

Например, мы можем использовать его для обозначения JDK 1.7:

/**
 * @version JDK 1.7
 */

Когда мы используем тег @version , у него есть два разных сценария использования:

  • Запишите версию одного файла
  • Отметьте версию всего программного обеспечения

Очевидно, мы видим, что между этими двумя сценариями существует несоответствие. Это связано с тем, что версия отдельного файла может быть несовместима с версией программного обеспечения. Кроме того, разные файлы могут иметь разные версии файлов. Итак, как мы должны использовать тег @version ?

В прошлом Sun использовала тег @version для записи версии отдельного файла. Также было рекомендовано использовать в теге @version строку SCCS « %I%, %G% ». Затем SCCS заменит « %I% » на текущую версию файла, а « %G% » на дату «мм/дд/гг» при извлечении файла. Например, это будет выглядеть как «1.39, 28/02/97» (мм/дд/гг). Кроме того, %I% увеличивается каждый раз, когда мы редактируем и удаляем (дельта + получаем) файл.

SCCS также известна как система контроля исходного кода. Если мы хотим узнать больше о команде SCCS, мы можем обратиться к ней здесь . Кроме того, SCCS — это устаревшая система контроля версий исходного кода.

В настоящее время мы склонны использовать тег @version для указания версии всего программного обеспечения. В свете этого он делает ненужным размещение тега @version в одном файле.

Означает ли это, что версия отдельного файла больше не важна? На самом деле это не так. Теперь у нас есть модернизированное программное обеспечение для контроля версий, такое как Git, SVN, CVS и так далее. Каждое программное обеспечение для контроля версий имеет свой уникальный способ записи версии каждого отдельного файла, и ему не нужно полагаться на тег @version .

Возьмем в качестве примера Oracle JDK 8. Если мы посмотрим на исходный код в файле src.zip , мы обнаружим, что только класс java.awt.Color имеет тег @version :

/**
 * @version     10 Feb 1997
 */

Таким образом, мы можем сделать вывод, что использование тега @version для указания версии одного файла исчезает. Таким образом, документ Oracle предлагает использовать тег @version для записи номера текущей версии программного обеспечения.

2.2. @поскольку​

Формат тега @since довольно прост:

@since  since-text

Например, мы можем использовать его, чтобы отметить функцию, представленную в JDK 1.7:

/**
 * @since JDK 1.7
 */

Короче говоря, мы используем тег @since , чтобы описать, когда впервые появилось изменение или функция. Точно так же он использует версию выпуска всего программного обеспечения, а не версию отдельного файла. Документ Oracle дает нам несколько подробных инструкций по использованию тега @since :

  • При введении нового пакета мы должны указать тег @since в описании пакета и каждого его класса.
  • При добавлении нового класса или интерфейса мы должны указывать один тег @since в описании класса, а не в описании членов класса.
  • Если мы добавляем новых членов в существующий класс, мы должны указывать теги @since только для вновь добавленных членов, а не в описании класса.
  • Если мы изменим член класса с защищенного на общедоступный в более позднем выпуске, мы не должны изменять тег @since .

Иногда тег @since очень важен, потому что он дает важную подсказку о том, что пользователи программного обеспечения должны ожидать определенную функцию только после определенной версии выпуска.

Если мы еще раз взглянем на файл src.zip , мы можем найти много случаев использования тега @since . Возьмем в качестве примера класс java.lang.FunctionalInterface : 

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

Из этого фрагмента кода мы можем узнать, что класс FunctionalInterface доступен только в JDK 8 и выше.

3. Сходства между @version и @since​

В этом разделе мы рассмотрим сходство между тегами @version и @since .

3.1. Оба принадлежат блочным тегам​

Во- первых, и @version , и @since относятся к блочным тегам.

В комментариях к документу теги можно разделить на два типа:

  • Блокировать теги
  • Встроенные теги

Тег блока имеет форму @tag . И он должен появляться в начале строки, игнорируя начальные звездочки, пробелы и разделитель ( /** ). Например, мы можем использовать @version и @since в разделе тегов:

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

Однако встроенный тег имеет вид {@tag} . И он может существовать где угодно в описаниях или комментариях. Например, если у нас есть тег {@link} , мы можем использовать его в описании:

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

3.2. Оба могут быть использованы несколько раз​

Во- вторых, и @version , и @since можно использовать несколько раз. Сначала мы можем быть шокированы этим использованием. Затем мы можем задаться вопросом, как тег @version может появляться несколько раз в одном классе. Но это правда, и это задокументировано здесь . И это объясняет, что мы можем использовать один и тот же программный элемент более чем в одном API. Таким образом, мы можем прикрепить различные версии с одним и тем же программным элементом.

Например, если мы используем один и тот же класс или интерфейс в разных версиях ADK и JDK, мы можем предоставить разные сообщения @version и @since :

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

В сгенерированных HTML-страницах инструмент Javadoc будет вставлять запятую (,) и пробел между именами. Таким образом, текст версии выглядит так:

ADK 1.6, JDK 1.7

И, поскольку текст выглядит так:

ADK 1.3, JDK 1.4

4. Различия между @version и @since​

В этом разделе рассмотрим различия между тегами @version и @since .

4.1. Изменится ли их содержание​

Текст @version постоянно меняется, а текст @since стабилен. Со временем программное обеспечение постоянно совершенствуется. Будут присоединяться новые функции, поэтому его версия будет продолжать меняться. Однако тег @since указывает только момент времени в прошлом, когда появились новые изменения или функции.

4.2. Где их можно использовать​

Эти два тега имеют немного различное использование:

  • @version : обзор, пакет, класс, интерфейс
  • @since : обзор, пакет, класс, интерфейс, поле, конструктор, метод

Тег @since имеет более широкое применение и допустим в любом комментарии к документу . Напротив, тег @version имеет более узкий диапазон использования, и мы не можем использовать его в полях, конструкторах или методах.

4.3. Появляются ли они по умолчанию​

Эти два тега по умолчанию имеют разное поведение на сгенерированных HTML-страницах:

  • Текст @version не отображается по умолчанию
  • Текст @since появляется по умолчанию

Если мы хотим включить «текст версии» в сгенерированные документы, мы можем использовать опцию -version :

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

Точно так же, если мы хотим опустить «с текстом» в сгенерированных документах, мы можем использовать параметр -nosince :

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

5. Вывод​

В этом уроке мы впервые рассказали о том, как правильно использовать теги @version и @since . Затем мы описали сходства и различия между ними. Короче говоря, тег @version содержит номер текущей версии программного обеспечения, а тег @since описывает, когда впервые появилось изменение или функция.