Javadoc (первоначально в оболочке JavaDoc ) [1] - это генератор документации, созданный Sun Microsystems для языка Java (теперь принадлежащий Oracle Corporation ) для создания документации API в формате HTML из исходного кода Java . Формат HTML используется для добавления удобства возможности связывать связанные документы вместе. [2]
Формат «doc comments» [3], используемый Javadoc, является де-факто отраслевым стандартом для документирования классов Java. Некоторые IDE , [4] такие как IntelliJ IDEA , NetBeans и Eclipse , автоматически генерируют Javadoc HTML. Многие редакторы файлов помогают пользователю в создании исходного кода Javadoc и используют информацию Javadoc как внутренние ссылки для программиста.
Javadoc также предоставляет API для создания доклетов и теглетов , который позволяет пользователям анализировать структуру приложения Java. Вот как JDiff может генерировать отчеты об изменениях между двумя версиями API.
Javadoc не влияет на производительность в Java, так как все комментарии удаляются во время компиляции. Написание комментариев и документации Javadoc предназначено для лучшего понимания кода и, следовательно, для лучшего его обслуживания.
История
Javadoc был одним из первых генераторов документации на языке Java . [5] До использования генераторов документации было принято использовать технических писателей, которые обычно писали только автономную документацию для программного обеспечения, [6] но было намного сложнее поддерживать эту документацию в синхронизации с самим программным обеспечением.
Javadoc используется Java с момента первого выпуска и обычно обновляется при каждом новом выпуске Java Development Kit .
@field
Синтаксис Javadoc был эмулируется систем документации для других языков, в том числе перекрестного языка Doxygen , в JSDoc системы JavaScript, и Apple, HeaderDoc .
Техническая архитектура
Структура комментария Javadoc
Комментарий Javadoc отделяется от кода стандартными многострочными тегами комментариев /*
и */
. Открывающий тег (называемый разделителем начала комментария) имеет дополнительную звездочку, как в /**
.
- Первый абзац - это описание задокументированного метода.
- За описанием следует различное количество описательных тегов, обозначающих:
- Параметры метода (
@param
) - Что возвращает метод (
@return
) - Любые исключения, которые метод может бросить (
@throws
) - Другие менее распространенные теги, такие как
@see
(тег "см. Также")
- Параметры метода (
Обзор Javadoc
Основная структура написания комментариев к документу - встраивание их внутрь /** ... */
. Блок комментариев Javadoc располагается непосредственно над элементами без разделения новой строки. Обратите внимание, что любые операторы импорта должны предшествовать объявлению класса. Объявление класса обычно содержит:
// импортировать операторы/ ** * @author Имя Фамилия * @version 1.6 (номер текущей версии программы) * @since 1.2 (версия пакета, в который этот класс был впервые добавлен) * / public class Test { / / class body }
Для методов есть (1) краткое, краткое описание из одной строки, объясняющее, что делает элемент. За этим следует (2) более длинное описание, которое может охватывать несколько абзацев. Подробности можно полностью объяснить здесь. Этот раздел не является обязательным. Наконец, есть (3) раздел тегов, в котором перечислены принятые входные аргументы и возвращаемые значения метода. Обратите внимание, что вся документация Javadoc обрабатывается как HTML, поэтому разделы с несколькими абзацами разделяются тегом разрыва абзаца " ".
/ ** * Краткое однострочное описание. (1) *
* Более подробное описание. Если бы они были, это было бы (2) * здесь. *
* И еще больше объяснений, которые нужно следовать в следующих * абзацах, разделенных разрывами абзаца HTML. * * @param переменная Описание текст текст текст. (3) * @return Текст описания текстовый текст. * / public int methodName (...) { // тело метода с оператором возврата }
Переменные документируются аналогично методам, за исключением того, что часть (3) опущена. Здесь переменная содержит только краткое описание:
/ ** * Описание переменной здесь. * / private int debug = 0 ;
Обратите внимание, что не рекомендуется [7] определять несколько переменных в одном комментарии к документации. Это связано с тем, что Javadoc считывает каждую переменную и помещает их отдельно на сгенерированную HTML-страницу с тем же комментарием документации, который копируется для всех полей.
/ ** * Расстояние по горизонтали и вертикали до точки (x, y) * / public int x , y ; // ИЗБЕГАТЬ
Вместо этого рекомендуется записывать и документировать каждую переменную отдельно:
/ ** * Горизонтальное расстояние точки. * / public int x ;/ ** * Вертикальное расстояние точки. * / public int y ;
Таблица тегов Javadoc
Некоторые из доступных тегов Javadoc [8] перечислены в таблице ниже:
Тег и параметр | Применение | Относится к | С |
---|---|---|---|
@author Джон Смит | Описывает автора. | Класс, Интерфейс, Перечисление | |
{ @docRoot } | Представляет относительный путь к корневому каталогу сгенерированного документа от любой сгенерированной страницы. | Класс, Интерфейс, Перечисление, Поле, Метод | |
версия @version | Обеспечивает ввод версии программного обеспечения. Максимум один на класс или интерфейс. | Класс, Интерфейс, Перечисление | |
@since с-текст | Описывает, когда эта функция впервые появилась. | Класс, Интерфейс, Перечисление, Поле, Метод | |
@ см. ссылку | Ссылка на другой элемент документации. | Класс, Интерфейс, Перечисление, Поле, Метод | |
@param имя описание | Описывает параметр метода. | Методика | |
@return описание | Описывает возвращаемое значение. | Методика | |
@exception classname description @throws classname description | Описывает исключение, которое может быть вызвано этим методом. | Методика | |
@ устаревшее описание | Описывает устаревший метод. | Класс, Интерфейс, Перечисление, Поле, Метод | |
{ @inheritDoc } | Копирует описание из переопределенного метода. | Метод переопределения | 1.4.0 |
{ @link reference } | Ссылка на другой символ. | Класс, Интерфейс, Перечисление, Поле, Метод | |
{ @linkplain reference } | Идентично {@link}, за исключением того, что подпись ссылки отображается в виде обычного текста, а не шрифта кода. | Класс, Интерфейс, Перечисление, Поле, Метод | |
{ @value #STATIC_FIELD } | Вернуть значение статического поля. | Статическое поле | 1.4.0 |
{ @code literal } | Форматирует буквальный текст шрифтом кода. Это эквивалент {@literal} . | Класс, Интерфейс, Перечисление, Поле, Метод | 1.5.0 |
{ @literal literal } | Обозначает буквальный текст. Заключенный текст интерпретируется как не содержащий разметки HTML или вложенных тегов javadoc. | Класс, Интерфейс, Перечисление, Поле, Метод | 1.5.0 |
{ @serial literal } | Используется в комментарии к документу для сериализуемого поля по умолчанию. | Поле | |
{ @serialData literal } | Документирует данные, записанные методами writeObject () или writeExternal (). | Поле, Метод | |
{ @serialField literal } | Документирует компонент 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 }
Смотрите также
Рекомендации
- ^ Теперь в корпусе "Javadoc". См. [1] . Первоначально в корпусе «JavaDoc». См. [2]
- ^ https://web.archive.org/web/20170613233020/http://agile.csc.ncsu.edu/SEMaterials/tutorials/javadoc/
- ^ "javadoc - Генератор документации Java API" . Sun Microsystems . Проверено 30 сентября 2011 ..
- ^ IntelliJ IDEA , NetBeans, заархивировано 5 апреля 2017 г. на Wayback Machine и Eclipse
- ^ «Как писать комментарии к документам для инструмента Javadoc Tool» . Sun Microsystems . Проверено 30 сентября 2011 ..
- ^ Веннерс, Билл; Гослинг, Джеймс; и другие. (2003-07-08). «Визуализация с помощью JavaDoc» . artima.com . Проверено 19 января 2013 .
Когда я создавал исходный JavaDoc в исходном компиляторе, даже мои близкие люди довольно жестко его критиковали. И это было интересно, потому что обычно критиковали: хороший технический писатель мог бы сделать намного лучше, чем это делает JavaDoc. И ответ - да, но сколько API на самом деле задокументировано хорошими техническими писателями? И сколько из них на самом деле обновляют свою документацию достаточно часто, чтобы быть полезными?
- ^ «Платформа Java, Справочник по инструментам Standard Edition для Oracle JDK в Solaris, Linux и OS X, выпуск 8. Раздел« Объявления с несколькими полями » » . Дата обращения 20 декабря 2017 .
- ^ Спецификация комментариев к документации по JavaSE 13
Внешние ссылки
- Платформа Java, стандартная версия Руководство по документации Javadoc
- JSR 260 Javadoc Tag Technology Update Java Specification Request (определяет новые теги Javadoc)
- Улучшение Javadoc с помощью ashkelon
- Globaldocs: средство просмотра для одновременного просмотра нескольких документов Javadocs.
- Различные документы Java, преобразованные в формат справки Windows