Javadoc: @ версия и @since

Question

Есть ли причина включать в класс как @version, так и @since?

Они кажутся взаимоисключающими.

Кроме того, что означают %I% и %G% и как их устанавливать / использовать?

 @version %I%, %G% 

Спасибо

Answer 1

Тег @version должен быть текущей версией выпуска или рассматриваемого файла. Синтаксис %I%, %G% - это макросы, которые программа управления исходным кодом заменит на текущую версию файла и дату извлечения файла.

Тег @since должен использоваться для определения, какую версию вы добавили, метод, класс и т. Д. Это ваш совет другим разработчикам, что они должны ожидать, что метод будет работать только при выполнении определенной версии пакета. Я бы рассмотрел эти очень важные части документации, если вы отправляете свой код в виде библиотеки, предназначенной для использования кем-то другим.

Answer 2

Объяснено в статье из Oracle, Как писать комментарии к документу для инструмента Javadoc .

@version

… только классы и интерфейсы.

В Java Software мы используем @version для версии SCCS. Смотрите "man sccs-get" для деталей. Консенсус выглядит следующим образом:

% I% увеличивается каждый раз, когда вы редактируете и добавляете файл в файл

% G% - это дата, мм / дд / гг

При создании файла% I% устанавливается на 1,1. Когда вы редактируете и удаляете его, он увеличивается до 1,2.

Некоторые разработчики опускают дату% G% (и делают это), если считают ее слишком запутанной - например, 3/4/96, которую% G% будет производить за 4 марта, будет интерпретироваться этими за пределами Соединенных Штатов, чтобы означать 3 апреля. Некоторые разработчики включают время% U% только в том случае, если им нужно более точное разрешение (из-за многократной регистрации за день).

Самым чистым числовым форматом даты будет формат даты с первым годом, например, гггг-мм-дд, как предлагается в ISO 8601 и в других местах (например, http://www.cl.cam.ac.uk/~mgk25/iso-time.html),, но для этого необходимо исходить из SCCS.

@since

Укажите версию продукта, когда имя Java было добавлено в спецификацию API (если отличается от реализации). Например, если пакет, класс, интерфейс или член был добавлен в платформу Java 2, Standard Edition, API Specification в версии 1.2, используйте:

/**
 * @since 1.2
 */

Стандартный доклет Javadoc отображает подзаголовок «С» со строковым аргументом в качестве текста. Этот подзаголовок появляется в сгенерированном тексте только в месте, соответствующем тому, где тег @since появляется в исходных комментариях к документу (инструмент Javadoc не распространяет его вниз по иерархии).

(Когда-то это было соглашение "@since JDK1.2", но поскольку это спецификация платформы Java, не относящаяся к Oracle JDK или SDK, мы удалили "JDK".)

Когда пакет представлен, укажите тег @since в его описании пакета и в каждом из его классов. (Добавление тегов @since к каждому классу технически не требуется, но является нашим соглашением, поскольку обеспечивает лучшую видимость в исходном коде.) При отсутствии переопределяющих тегов значение тега @since применяется к каждому из классов пакета и члены.

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

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

Answer 3

Не понимаю, насколько они взаимоисключающие. Один используется для определения версии, а другой - для описания того, когда метод существует. Например:

/**
 * Does Whatever
 * @version 1.2.3
 * @since 1.2.0
 *
 */
public void myMethod() {
    // .......
}

Что касается персонажей, которых вы упомянули, они кажутся частными, и в любом случае я понятия не имею, что они означают.

Answer 4

@version будет записываться при каждом редактировании. [1.3.21]

@since означает, с какой версии выпуска будет поддерживаться этот интерфейс или т. Ювал Адам интересен, но это не стандарт, цель java doc - понять каждый.