Javadoc

Javadoc — генератор документации, созданный Sun Microsystems для языка Java (сейчас принадлежит корпорации Oracle ) для создания документации API в формате HTML из исходного кода Java . Формат HTML используется для удобства создания гиперссылок на связанные документы. ^[1]

Формат «комментариев к документу» ^[2] используемый Javadoc, является де-факто отраслевым стандартом для документирования классов Java. Некоторые IDE , ^[3] такие как IntelliJ IDEA , NetBeans и Eclipse , автоматически генерируют шаблоны Javadoc. Многие редакторы файлов помогают пользователю создавать исходный код Javadoc и использовать информацию Javadoc в качестве внутренних ссылок для программиста.

Javadoc также предоставляет API для создания доклетов и таглетов, который позволяет пользователям анализировать структуру приложения Java. Именно так JDiff может генерировать отчеты о том, что изменилось между двумя версиями API.

Javadoc не влияет на производительность Java, поскольку все комментарии удаляются во время компиляции. Написание комментариев и Javadoc предназначено для лучшего понимания кода и, следовательно, лучшего его обслуживания.

История

Javadoc был одним из первых генераторов документации на языке Java . ^[4] До использования генераторов документации было принято нанимать технических писателей, которые обычно писали только отдельную документацию для программного обеспечения. ^[5] но было гораздо сложнее синхронизировать эту документацию с самим программным обеспечением.

Javadoc используется Java с момента первого выпуска и обычно обновляется при каждом новом выпуске Java Development Kit .

The @field Синтаксис Javadoc эмулируется системами документации для других языков, включая межъязыковую систему Doxygen , систему JSDoc для JavaScript и Apple HeaderDoc .

Техническая архитектура

Структура комментария Javadoc

Комментарий Javadoc выделяется из кода стандартными тегами многострочных комментариев. /* и */. Открывающий тег (называемый разделителем начального комментария) имеет дополнительную звездочку, как в /**.

Первый абзац представляет собой описание документированного метода.
После описания следует различное количество описательных тегов, означающих:
1. Параметры метода ( @param)
2. Что возвращает метод ( @return)
3. Любые исключения, которые может выдать метод ( @throws)
4. Другие менее распространенные теги, такие как @see (тег «см. также»)

Обзор Javadoc

Основная структура написания комментариев к документу заключается в их встраивании внутрь. /** ... */. Блок комментариев Javadoc расположен непосредственно над элементами. без разделительной новой строки. Обратите внимание, что любые операторы импорта должны предшествовать объявлению класса. Объявление класса обычно содержит:

// import statements

/**
 * @author      Firstname Lastname <address @ example.com>
 * @version     1.6                 (current version number of program)
 * @since       1.2          (the version of the package this class was first added to)
 */
public class Test {
    // class body
}

Для методов имеется (1) краткое, лаконичное описание в одну строку. объясните, что делает этот предмет. Далее следует (2) более длинный описание, которое может охватывать несколько абзацев. Подробности можно объяснить полностью здесь. Этот раздел необязательный. Наконец, есть (3) раздел тегов для перечисления принятых входных данных. аргументы и возвращаемые значения метода. Обратите внимание, что все Javadoc рассматривается как HTML, поэтому разделы с несколькими абзацами разделены знаком " <p>"Тег разрыва абзаца.

/**
 * Short one line description.                           (1)
 * <p>
 * Longer description. If there were any, it would be    (2)
 * here.
 * <p>
 * And even more explanations to follow in consecutive
 * paragraphs separated by HTML paragraph breaks.
 *
 * @param  variable Description text text text.          (3)
 * @return Description text text text.
 */
public int methodName (...) {
    // method body with a return statement
}

Переменные документируются аналогично методам, за исключением того, что часть (3) опущена. Здесь переменная содержит только короткое описание:

/**
 * Description of the variable here.
 */
private int debug = 0;

Обратите внимание, что не рекомендуется ^[6] определить несколько переменных в одном комментарии к документации. Это связано с тем, что Javadoc считывает каждую переменную и помещает их отдельно на сгенерированную HTML-страницу с тем же комментарием к документации, который копируется для всех полей.

/**
 * The horizontal and vertical distances of point (x,y)
 */
public int x, y;      // AVOID

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

/**
 * The horizontal distance of point.
 */
public int x;

/**
 * The vertical distance of point.
 */
public int y;

Таблица тегов Javadoc

Некоторые из доступных тегов Javadoc ^[7] перечислены в таблице ниже:

Тег и параметр	Использование	Применяется к	С
@автор Джон Смит	Описывает автора.	Класс, Интерфейс, Перечисление
{ @docRoot }	Представляет относительный путь к корневому каталогу созданного документа на любой созданной странице.	Класс, Интерфейс, Перечисление, Поле, Метод
@version версия	Предоставляет информацию о версии программного обеспечения.	Модуль, Пакет, Класс, Интерфейс, Перечисление
@since с тех пор-текст	Описывает, когда эта функция впервые появилась.	Класс, Интерфейс, Перечисление, Поле, Метод
@см. ссылку	Предоставляет ссылку на другой элемент документации.	Класс, Интерфейс, Перечисление, Поле, Метод
@param описание имени	Описывает параметр метода.	Метод
@return описание	Описывает возвращаемое значение.	Метод
@Exception Описание имени класса @throws описание имени класса	Описывает исключение, которое может быть выброшено этим методом.	Метод
@устаревшее описание	Описывает устаревший метод.	Класс, Интерфейс, Перечисление, Поле, Метод
{ @inheritDoc }	Копирует описание из переопределенного метода.	Переопределяющий метод	1.4.0
{ @link `ссылка` }	Ссылка на другой символ.	Класс, Интерфейс, Перечисление, Поле, Метод
{ @linkplain `ссылка` }	Идентичен {@link}, за исключением того, что метка ссылки отображается обычным текстом, а не шрифтом кода.	Класс, Интерфейс, Перечисление, Поле, Метод
{ @value #STATIC_FIELD }	Вернуть значение статического поля.	Статическое поле	1.4.0
{ @code литерал }	Форматирует обычный текст шрифтом кода. Он эквивалентен <code>{@literal</code>.	Класс, Интерфейс, Перечисление, Поле, Метод	1.5.0
{ @literal литерал }	Обозначает буквальный текст. Приложенный текст интерпретируется как не содержащий HTML-разметки или вложенных тегов Javadoc.	Класс, Интерфейс, Перечисление, Поле, Метод	1.5.0
{ @serial литерал }	Используется в комментарии к документу для сериализуемого поля по умолчанию.	Поле
{ @serialData литерал }	Документирует данные, записанные методами writeObject() или writeExternal().	Поле, Метод
{ @serialField литерал }	Документирует компонент ObjectStreamField.	Поле

Примеры

Ниже приведен пример Javadoc для документирования метода. Обратите внимание, что интервалы и количество символов в этом примере указаны в соответствии с соглашением.

/**
 * Validates a chess move.
 *
 * <p>Use {@link #doMove(int fromFile, int fromRank, int toFile, int toRank)} to move a piece.
 *
 * @param fromFile file from which a piece is being moved
 * @param fromRank rank from which a piece is being moved
 * @param toFile   file to which a piece is being moved
 * @param toRank   rank to which a piece is being moved
 * @return            true if the move is valid, otherwise false
 * @since             1.0
 */
boolean isValidMove(int fromFile, int fromRank, int toFile, int toRank) {
    // ...body
}

/**
 * Moves a chess piece.
 *
 * @see java.math.RoundingMode
 */
void doMove(int fromFile, int fromRank, int toFile, int toRank)  {
    // ...body
}

Доклеты

Программы Doclet работают с инструментом Javadoc для создания документации из кода, написанного на Java . ^[8]

Доклеты написаны на языке программирования Java и используют Doclet API к:

Выберите, какой контент включить в документацию
Формат представления контента
Создайте файл, содержащий документацию.

The StandardDoclet[1], включенный в Javadoc, генерирует документацию API файлов на основе фреймов в виде HTML- . В Интернете доступно множество нестандартных документов. ^{[ нужна ссылка ]}, часто бесплатно. Их можно использовать для:

Создание других типов документации, не относящихся к API.
Вывод документации в файлы других типов, отличных от HTML, например PDF.
Вывод документации в формате HTML с дополнительными функциями, такими как поиск или встроенными диаграммами UML, созданными на основе классов Java.

См. также

Ссылки

^ «Явадок» . agile.csc.ncsu.edu . Архивировано из оригинала 13 июня 2017 года . Проверено 12 января 2022 г.
^ «javadoc — Генератор документации Java API» . Сан Микросистемс . Проверено 30 сентября 2011 г. .
^ IntelliJ IDEA , NetBeans. Архивировано 5 апреля 2017 г. в Wayback Machine и Eclipse.
^ «Как писать комментарии к документу для инструмента Javadoc» . Сан Микросистемс . Проверено 30 сентября 2011 г. .
^ Веннерс, Билл; Гослинг, Джеймс; и др. (08 июля 2003 г.). «Визуализация с помощью JavaDoc» . artima.com . Проверено 19 января 2013 г. Когда я делал оригинальный JavaDoc в оригинальном компиляторе, даже окружающие меня люди довольно здраво его раскритиковали. И это было интересно, потому что обычная критика заключалась в следующем: хороший технический писатель мог бы сделать гораздо лучшую работу, чем JavaDoc. И ответ: ну да, но сколько API на самом деле задокументировано хорошими техническими авторами? И сколько из них действительно обновляют свою документацию достаточно часто, чтобы быть полезной?
^ «Платформа Java, Справочник по инструментам стандартной версии для Oracle JDK в Solaris, Linux и OS X, выпуск 8. Раздел «Объявления с несколькими полями» » . Проверено 20 декабря 2017 г.
^ Спецификация комментариев к документации JavaSE 13
^ «Обзор доклетов» .

Внешние ссылки

Платформа Java, стандартная версия Руководство по Javadoc
JSR 260 на обновление технологии тегов Javadoc Запрос (определяет новые теги Javadoc)
Улучшите Javadoc с помощью Ashkelon
Различная документация Java, преобразованная в формат справки Windows.

[1] «Явадок» . agile.csc.ncsu.edu . Архивировано из оригинала 13 июня 2017 года . Проверено 12 января 2022 г.

[2] «javadoc — Генератор документации Java API» . Сан Микросистемс . Проверено 30 сентября 2011 г. .

[3] IntelliJ IDEA , NetBeans. Архивировано 5 апреля 2017 г. в Wayback Machine и Eclipse.

[4] «Как писать комментарии к документу для инструмента Javadoc» . Сан Микросистемс . Проверено 30 сентября 2011 г. .

[5] Веннерс, Билл; Гослинг, Джеймс; и др. (08 июля 2003 г.). «Визуализация с помощью JavaDoc» . artima.com . Проверено 19 января 2013 г. Когда я делал оригинальный JavaDoc в оригинальном компиляторе, даже окружающие меня люди довольно здраво его раскритиковали. И это было интересно, потому что обычная критика заключалась в следующем: хороший технический писатель мог бы сделать гораздо лучшую работу, чем JavaDoc. И ответ: ну да, но сколько API на самом деле задокументировано хорошими техническими авторами? И сколько из них действительно обновляют свою документацию достаточно часто, чтобы быть полезной?

[6] «Платформа Java, Справочник по инструментам стандартной версии для Oracle JDK в Solaris, Linux и OS X, выпуск 8. Раздел «Объявления с несколькими полями» » . Проверено 20 декабря 2017 г.

[7] Спецификация комментариев к документации JavaSE 13

[8] «Обзор доклетов» .

[1]

[2]

[3]

[4]

[5]

[6]

[7]

[8]