Javadoc

редактировать
Генератор документации для Java

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

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

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

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

Содержание

  • 1 История
  • 2 Техническая архитектура
    • 2.1 Структура комментария Javadoc
    • 2.2 Обзор Javadoc
    • 2.3 Таблица тегов Javadoc
    • 2.4 Примеры
  • 3 См. Также
  • 4 Ссылки
  • 5 Внешние ссылки

История

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

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

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

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

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

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

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

Обзор Javadoc

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

// операторы импорта / ** * @author Имя Фамилия 
* @version 1.6 (номер текущей версии программы) * @since 1.2 (версия пакета, в которую этот класс был впервые добавлен) * / public class Test { // класс body}

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

».

/ ** * Краткое однострочное описание. (1) * 

* Более подробное описание. Если бы они были, это было бы (2) * здесь. *

* И еще больше объяснений, которые нужно следовать в следующих * абзацах, разделенных разрывами абзаца HTML. * * @param переменная Описание текст текст текст. (3) * @return Текст описания текстовый текст. * / public int methodName (...) {// тело метода с оператором возврата}

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

/ ** * Здесь описание переменной. * / private int debug = 0;

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

/ ** * Расстояние по горизонтали и вертикали до точки (x, y) * / public int x, y; // ИЗБЕГАЙТЕ

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

/ ** * Горизонтальные расстояния точки. * / public int x; / ** * Вертикальные расстояния точки. * / public int y;

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

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

Тег и параметрИспользованиеПрименимо кТак как
@author Джон СмитОписывает автора.Класс, Интерфейс, Enum
{@docRoot }Представляет относительный путь к сгенерированному корневой каталог документа с любой сгенерированной страницы.Класс, Интерфейс, Перечисление, Поле, Метод
@versionversionОбеспечивает запись версии программного обеспечения. Не более одного для каждого класса или интерфейса.Class, Interface, Enum
@since Since-textОписывает, когда эта функция впервые появилась.Class, Интерфейс, Перечисление, Поле, Метод
@see ссылкаПредоставляет ссылку на другой элемент документации.Класс, Интерфейс, Перечисление, Поле, Метод
@param имя описаниеОписывает параметр метода.Метод
@return описаниеОписывает возвращаемое значение.Метод
@exception описание имени класса. @throws описание имени классаОписывает исключение, которое может быть вызвано этим методом.Метод
@deprecated descriptionОписывает устаревший метод.Class, Interface, Enum, Field, Method
{@inheritDoc }Копирует описание из замещенного метода.Метод переопределения1.4.0
{@linkссылка}Ссылка на другой символ.Class, Interface, Enum, Field, Метод
{@linkplain ссылка}Идентичный на {@link}, за исключением того, что подпись ссылки отображается в виде обычного текста, а не шрифта кода.Класс, Интерфейс, Перечисление, Поле, Метод
{@value#STATIC_FIELD}Возвращает значение статического поля.Статическое поле1.4.0
{@codeliteral}Форматирует буквальный текст шрифтом кода. Это эквивалентно {@literal}.Class, Interface, Enum, Field, Method1.5.0
{@literalliteral}Обозначает буквальный текст. Заключенный текст интерпретируется как не содержащий разметки HTML или вложенных тегов javadoc.Class, Interface, Enum, Field, Method1.5.0
{@serial literal}Используется в комментарии документа для сериализуемого поля по умолчанию.Поле
{@serialData literal}Документирует данные, записанные методами writeObject () или writeExternal ().Поле, метод
{@serialField литерал}Документирует компонент ObjectStreamField.Поле

Примеры

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

/ ** * Проверяет шахматный ход. * * 

Используйте {@link #doMove (int fromFile, int fromRank, int toFile, int toRank)} для перемещения фигуры. * * @param fromFile файл, из которого перемещается фигура * @param fromRank rank, из которого перемещается фигура * @param toFile файл, в который перемещается фигура * @param toRank ранг, в который перемещается фигура * @return true, если ход допустим, иначе false * @since 1.0 * / boolean isValidMove (int fromFile, int fromRank, int toFile, int toRank) {//... body} / ** * Перемещает шахматную фигуру. * * @see java.math.RoundingMode * / void doMove (int fromFile, int fromRank, int toFile, int toRank) {//... body}

См. также

Ссылки

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

Последняя правка сделана 2021-05-24 03:58:24
Содержание доступно по лицензии CC BY-SA 3.0 (если не указано иное).
Обратная связь: support@alphapedia.ru
Соглашение
О проекте