Javadoc - Javadoc

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

Формат "комментариев к документам"[3] используемый Javadoc является фактическим отраслевым стандартом для документирования классов Java. Немного Иды,[4] подобно IntelliJ IDEA, NetBeans и Затмение, автоматически генерировать Javadoc HTML. Многие редакторы файлов помогают пользователю в создании исходного кода Javadoc и используют информацию Javadoc в качестве внутренних ссылок для программиста.

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

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

История

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

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

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

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

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

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

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

Обзор Javadoc

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

// импорт операторов/** * @author Имя Фамилия <адрес @ example.com> * @version 1.6 (номер текущей версии программы) * @since 1.2 (версия пакета, в которую впервые был добавлен этот класс) */общественный учебный класс Тест {    // тело класса}

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

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

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

/** * Описание переменной здесь. */частный int отлаживать = 0;

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

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

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

/** * Горизонтальные расстояния точки. */общественный int Икс;/** * Вертикальные расстояния точки. */общественный int у;

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

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

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

Примеры

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

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

Смотрите также

Рекомендации

  1. ^ Теперь оформлен как «Javadoc». Видеть [1]. Первоначально в корпусе «JavaDoc». Видеть [2]
  2. ^ https://web.archive.org/web/20170613233020/http://agile.csc.ncsu.edu/SEMaterials/tutorials/javadoc/
  3. ^ "javadoc - Генератор документации Java API". Sun Microsystems. Получено 2011-09-30..
  4. ^ IntelliJ IDEA, NetBeans В архиве 2017-04-05 в Wayback Machine и Затмение
  5. ^ «Как писать комментарии к документам для инструмента Javadoc». Sun Microsystems. Получено 2011-09-30..
  6. ^ Веннерс, Билл; Гослинг, Джеймс; и другие. (2003-07-08). «Визуализация с помощью JavaDoc». artima.com. Получено 2013-01-19. Когда я создавал исходный JavaDoc в исходном компиляторе, даже мои близкие люди довольно резко критиковали его. И это было интересно, потому что обычно критиковали: хороший технический писатель мог бы сделать намного лучше, чем это делает JavaDoc. И ответ: да, но сколько API на самом деле задокументировано хорошими техническими писателями? И сколько из них действительно обновляют свою документацию достаточно часто, чтобы быть полезными?
  7. ^ "Платформа Java, Справочник по инструментам Standard Edition для Oracle JDK в Solaris, Linux и OS X, выпуск 8. Раздел" Объявления с несколькими полями"". Получено 20 декабря 2017.
  8. ^ Спецификация комментариев к документации JavaSE 13

внешняя ссылка