Javadoc - Javadoc

Скриншот

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

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

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

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

История

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

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

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

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

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

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

1. Первый абзац - это описание задокументированного метода.
2. За описанием следует различное количество описательных тегов, обозначающих:
   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;

Обратите внимание, что не рекомендуется определять несколько переменных в одном комментарии к документации. Это связано с тем, что 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 перечислены в таблице ниже:

Примеры

Ниже приводится пример документации 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
}

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

• Сравнение генераторов документации
• Комментарии к документации .NET XML

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

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

• Платформа Java, стандартная версия Руководство по документации Javadoc
• JSR 260 Javadoc Tag Technology Update Java Specification Request (определяет новые теги Javadoc)
• Улучшение Javadoc с помощью ashkelon
• Globaldocs: средство просмотра для одновременного просмотра нескольких документов Javadocs.
• Различные документы Java, преобразованные в формат справки Windows