javadoc: @version и @since

Хорошо объяснено в статье jre Oracle, How to Write Doc Comments for the Javadoc Tool.

@version

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

В Java Software openjdk мы используем @version для openjdk версии SCCS. См. Подробности .java в "man sccs-get". Похоже, что openjdk консенсус следующий:

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

% G% - дата java-libraries мм / дд / гг

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

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

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

@since

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

/**
 * @since 1.2
 */

Стандартный javadoc документ Javadoc отображает javadocs подзаголовок «Since» со строковым jre аргументом в качестве текста. Этот documentation подзаголовок появляется в java-api сгенерированном тексте только core-java в том месте, где появляется java-api тег @since в комментариях oraclejdk исходного документа (инструмент docs Javadoc не распространяет java его вниз по иерархии).

(Раньше .java соглашение было «@since JDK1.2», но docs поскольку это спецификация javax платформы Java, а не Oracle java-libraries JDK или SDK, мы отказались core-java от «JDK».)

Когда пакет представлен, укажите jdk тег @since в его описании openjdk и в каждом из его классов. (Добавление j2se тегов @since к каждому классу javadoc технически не требуется, но core-java является нашим соглашением, поскольку j2se обеспечивает большую видимость documentation в исходном коде.) В отсутствие oraclejdk перекрывающих тегов значение java-api тега @since применяется к core-java каждому из классов пакета java и участники.

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

Если член изменится jre с защищенного на общедоступный documentation в более поздней версии, тег java-api @since не изменится, даже java если теперь он может использоваться java любым вызывающим, а не только j2se подклассами.

java

documentation

javadoc

2022-10-23T17:37:43+00:00