Ответ 1

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

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

Ответ 2

В статье из Oracle хорошо сказано, Как написать комментарии к Doc для инструмента Javadoc.

@version

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

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

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

% G% - дата mm/dd/yy

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

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

Самый четкий формат числовой даты должен состоять в том, чтобы иметь формат даты с первым годом, например, yyyy-mm-dd, как предлагается в 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 не изменится, хотя теперь он может использоваться любым вызывающим, а не только подклассами.

Ответ 3

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

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

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

Ответ 4

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

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