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 .
Синтаксис @fieldJavadoc эмулируется системами документации для других языков, включая межъязыковую систему Doxygen , систему JSDoc для JavaScript и Apple HeaderDoc .
Комментарий Javadoc выделяется из кода стандартными тегами многострочных комментариев /*и */. Открывающий тег (называемый разделителем начального комментария) имеет дополнительную звездочку, как в /**.
@param)@return)@throws)@see(тег «см. также»)Основная структура написания комментариев к документу заключается в их встраивании внутрь файла /** ... */. Блок комментариев Javadoc располагается непосредственно над элементами без какой-либо разделительной новой строки. Обратите внимание, что любые операторы импорта должны предшествовать объявлению класса. Объявление класса обычно содержит:
// операторы импорта/** * @author Имя Фамилия <адрес @ example.com> * @version 1.6 (номер текущей версии программы) * @since 1.2 (версия пакета, в который этот класс был впервые добавлен) */ public class Test { / / тело класса } Для методов есть (1) короткое, лаконичное описание в одну строку, объясняющее, что делает элемент. За этим следует (2) более подробное описание, которое может охватывать несколько абзацев. Подробности можно подробно объяснить здесь. Этот раздел является необязательным. Наконец, есть (3) раздел тегов для перечисления принятых входных аргументов и возвращаемых значений метода. Обратите внимание, что вся документация Javadoc обрабатывается как HTML, поэтому несколько разделов абзаца разделяются тегом <p>разрыва абзаца " ".
/** * Краткое однострочное описание. (1) * <p> * Более подробное описание. Если бы они были, это было бы (2) * здесь. * <p> * И еще больше объяснений в последовательных * абзацах, разделенных разрывами абзацев HTML. * * Переменная @param Описание текст текст текст. (3) * @return Текст описания текст текст. */ public int MethodName (...) { // тело метода с оператором возврата } Переменные документируются аналогично методам, за исключением того, что часть (3) опускается. Здесь переменная содержит только краткое описание:
/** * Здесь описание переменной. */ private int debug = 0 ; Обратите внимание, что не рекомендуется [6] определять несколько переменных в одном комментарии к документации. Это связано с тем, что Javadoc считывает каждую переменную и помещает их отдельно на сгенерированную HTML-страницу с тем же комментарием к документации, который копируется для всех полей.
/** * Горизонтальное и вертикальное расстояние от точки (x,y) */ public int x , y ; // ИЗБЕГАТЬ Вместо этого рекомендуется писать и документировать каждую переменную отдельно:
/** * Расстояние до точки по горизонтали. */ public int x ; /** * Расстояние до точки по вертикали. */ public int y ; Некоторые из доступных тегов Javadoc [7] перечислены в таблице ниже:
Ниже приведен пример Javadoc для документирования метода. Обратите внимание, что интервалы и количество символов в этом примере указаны в соответствии с соглашением.
/** * Проверяет шахматный ход. * * <p>Используйте {@link #doMove(int fromFile, int fromRank, int toFile, int toRank)}, чтобы переместить фигуру. * * @param fromFile файл, из которого перемещается часть * @param fromRank ранг, из которого перемещается часть * @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 } Программы Doclet работают с инструментом Javadoc для создания документации из кода, написанного на Java . [8]
Доклеты написаны на языке программирования Java и используют их Doclet APIдля:
[ StandardDoclet1], включенный в Javadoc, генерирует документацию API в виде HTML- файлов на основе фреймов . Многие нестандартные доклеты доступны в сети [ нужна цитация ] , часто бесплатно. Их можно использовать для:
Когда я делал оригинальный JavaDoc в оригинальном компиляторе, даже окружающие меня люди довольно здраво его раскритиковали. И это было интересно, потому что обычная критика заключалась в следующем: хороший технический писатель мог бы сделать гораздо лучшую работу, чем JavaDoc. И ответ: ну да, но сколько API на самом деле задокументировано хорошими техническими авторами? И сколько из них действительно обновляют свою документацию достаточно часто, чтобы быть полезной?