Управление тегом Javadoc @since

Инструменты API предоставляют поддержку управления тегами Javadoc @since в новых элементах, добавленных в API (типы, методы, поля и т. д.). Новыми элементами API могут быть новый тип, добавленный в пакет API, новый тип, добавленный в тип API, новый метод, добавленный в тип API, или новое поле, добавленное в тип API. Добавление метода - это специальный случай, когда добавлением метода может быть добавление метода в тип, переопределение метода родительского класса, реализация метода родительского интерфейса или изменение существующей сигнатуры метода.

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

Инструментарий предусматривает следующую проверку для тегов @since:

Параметры управления тегами @since можно изменить на странице параметров Открывает страницу параметров Консоль Разработка модулей > Ошибки/предупреждения API.

Пропущенные теги @since

Каждый обнаруженный новый элемент API будет проверен инструментарием на наличие тега @since. Если новый элемент не содержит тега @since, то он будет отмечен как требующий тега и будет предложена версия тега. Предложенной версией нового тега будет текущая версия пакета, кроме случая нарушения изменения API, когда версия пакета тоже требует обновления. Если версия пакета тоже требует обновления, то предложенной версией для отсутствующего тега @since будет предложенная версией пакета.

Рассмотрим следующий пример: версия пакета A 1.0.0 и класс C был загружен в версию 1.1.0 A с методом m1().

Искаженные теги @since

Теги @since новых элементов могут проверяться на соответствие и правильность составления. Инструменты API выполняют проверку всех тегов @since на соответствие следующему общему формату:

[@since] [начальная-часть] [версия части 2] [заключительная-часть]

Рассмотрим следующие примеры тегов @since:

Недопустимые версии тегов @since

Теги @since новых элементов могут проверяться на правильность. Тег @since считается правильным, если информация о версии в теге совпадает с версией пакета.

Рассмотрим следующий пример, когда новый метод m2() был добавлен в класс API в пакете A с версией 1.0.0:

Связанные задачи
Настройка контрольной версии

Связанная ссылка
Параметры контрольной версии API
Параметры ошибок и предупреждений API