Перейти к основному содержимому

Введение в Javadoc

· 6 мин. чтения

1. Обзор​

Хорошая документация API — один из многих факторов, способствующих общему успеху программного проекта.

К счастью, все современные версии JDK предоставляют инструмент Javadoc для создания документации API из комментариев, присутствующих в исходном коде.

Предпосылки:

  1. JDK 1.4 (JDK 7+ рекомендуется для последней версии подключаемого модуля Maven Javadoc)
  2. Папка JDK /bin добавлена в переменную среды PATH .
  3. (Необязательно) IDE со встроенными инструментами

2. Комментарии Javadoc​

Начнем с комментариев.

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

// This is a single line comment

/*
 * This is a regular multi-line comment
 */

/**
 * This is a Javadoc
 */

Комментарии в стиле Javadoc также могут содержать теги HTML.

2.1. Формат Javadoc​

Комментарии Javadoc могут быть размещены над любым классом, методом или полем, которые мы хотим задокументировать.

Эти комментарии обычно состоят из двух разделов:

  1. Описание того, что мы комментируем
  2. Теги автономных блоков (отмеченные символом « @ »), которые описывают определенные метаданные .

В нашем примере мы будем использовать некоторые из наиболее распространенных блочных тегов. Полный список блочных тегов см. в справочном руководстве .

2.2. Javadoc на уровне класса​

Давайте посмотрим, как будет выглядеть комментарий Javadoc на уровне класса:

/**
* Hero is the main entity we'll be using to . . .
* 
* Please see the {@link com.foreach.javadoc.Person} class for true identity
* @author Captain America
* 
*/
public class SuperHero extends Person {
    // fields and methods
}

У нас есть краткое описание и два разных тега блока — автономный и встроенный:

  • Отдельные теги появляются после описания с тегом в качестве первого слова в строке, например, тег @author .
  • Встроенные теги могут появляться где угодно и заключаться в фигурные скобки , например, тег @link в описании.

В нашем примере мы также можем видеть два типа используемых блочных тегов:

  • {@link} предоставляет встроенную ссылку на указанную часть нашего исходного кода.
  • @author имя автора, добавившего класс, метод или поле, которое комментируется

2.3. Javadoc на полевом уровне​

Мы также можем использовать описание без каких-либо блочных тегов внутри нашего класса SuperHero :

/**
 * The public name of a hero that is common knowledge
 */
private String heroName;

Для частных полей не будет сгенерирован Javadoc, если мы явно не передаем параметр -private команде Javadoc.

2.4. Javadoc на уровне метода​

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

Давайте посмотрим на метод, который мы используем:

/**
 * <p>This is a simple description of the method. . .
 * <a href="http://www.supermanisthegreatest.com">Superman!</a>
 * </p>
 * @param incomingDamage the amount of incoming damage
 * @return the amount of health hero has after attack
 * @see <a href="http://www.link_to_jira/HERO-402">HERO-402</a>
 * @since 1.0
 */
public int successfullyAttacked(int incomingDamage) {
    // do things
    return 0;
}

Метод SuccessAttacked содержит как описание, так и многочисленные теги автономных блоков.

Существует множество блочных тегов, помогающих создавать надлежащую документацию, и мы можем включать всевозможную информацию. Мы даже можем использовать основные теги HTML в комментариях.

Давайте рассмотрим теги, с которыми мы сталкиваемся в приведенном выше примере:

  • @param предоставляет любое полезное описание параметра метода или входных данных, которые он должен ожидать.
  • @return предоставляет описание того, что метод будет или может вернуть.
  • @see сгенерирует ссылку, похожую на тег {@link} , но больше в контексте ссылки, а не встроенную.
  • @since указывает, какая версия класса, поля или метода была добавлена в проект.
  • @version указывает версию программного обеспечения, обычно используемую с макросами %I% и %G%.
  • @throws используется для дальнейшего объяснения случаев, когда программное обеспечение ожидает исключения
  • @deprecated дает объяснение того, почему код устарел, когда он мог устареть и каковы альтернативы.

Хотя оба раздела технически необязательны, нам понадобится по крайней мере один, чтобы инструмент Javadoc мог сгенерировать что-то осмысленное.

3. Генерация Javadoc​

Чтобы сгенерировать наши страницы Javadoc, нам нужно взглянуть на инструмент командной строки, который поставляется с JDK, и плагин Maven.

3.1. Инструмент командной строки Javadoc​

Инструмент командной строки Javadoc очень мощный, но с ним связаны некоторые сложности.

Запуск команды javadoc без каких-либо опций или параметров приведет к ошибке и ожидаемым выходным параметрам.

Нам нужно хотя бы указать, для какого пакета или класса мы хотим создать документацию.

Давайте откроем командную строку и перейдем в каталог проекта.

Предполагая, что все классы находятся в папке src в каталоге проекта: 

user@foreach:~$ javadoc -d doc src\*

Это создаст документацию в каталоге с именем doc , как указано с флагом –d . Если существует несколько пакетов или файлов, нам нужно предоставить их все.

Использование IDE со встроенной функциональностью, конечно, проще и обычно рекомендуется.

3.2. Javadoc с плагином Maven​

Мы также можем использовать плагин Maven Javadoc:

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-javadoc-plugin</artifactId>
            <version>3.0.0</version>
            <configuration>
                <source>1.8</source>
                <target>1.8</target>
            </configuration>
            <tags>
            ...
            </tags>
        </plugin>
    </plugins>
</build>

В базовом каталоге проекта мы запускаем команду для создания наших Javadocs в каталоге в target\site:

user@foreach:~$ mvn javadoc:javadoc

Плагин Maven очень мощный и упрощает создание сложных документов.

Давайте теперь посмотрим, как выглядит сгенерированная страница Javadoc:

./cbf9c6a042e6b5ed6e7b9b7a498a917b.png

Мы можем видеть древовидное представление классов, которые расширяет наш класс SuperHero . Мы можем увидеть наше описание, поля и метод, и мы можем щелкнуть ссылки для получения дополнительной информации.

Детальное представление нашего метода выглядит так:

./c46709b1701fd5b964a693a9fd3b8af3.png

3.3. Пользовательские теги Javadoc​

Помимо использования предопределенных тегов блоков для форматирования нашей документации, мы также можем создавать собственные теги блоков.

Для этого нам просто нужно включить параметр -tag в нашу командную строку Javadoc в формате <tag-name>:<locations-allowed>:<header> .

Чтобы создать собственный тег с именем @location , разрешенный где угодно, который отображается в заголовке «Известные местоположения» в нашем сгенерированном документе, нам нужно запустить:

user@foreach:~$ javadoc -tag location:a:"Notable Locations:" -d doc src\*

Чтобы использовать этот тег, мы можем добавить его в блок комментариев Javadoc:

/**
 * This is an example...
 * @location New York
 * @returns blah blah
 */

Плагин Maven Javadoc достаточно гибок, чтобы также разрешить определения наших пользовательских тегов в нашем pom.xml .

Чтобы установить тот же тег выше для нашего проекта, мы можем добавить следующее в раздел <tags> нашего плагина:

...
<tags>
    <tag>
        <name>location</name>
        <placement>a</placement>
        <head>Notable Places:</head>
    </tag> 
</tags>
...

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

4. Вывод​

В этом кратком вводном руководстве рассказывается, как писать базовые документы Javadoc и генерировать их с помощью командной строки Javadoc.

Более простой способ создать документацию — использовать любые встроенные параметры IDE или включить подключаемый модуль Maven в наш файл pom.xml и выполнить соответствующие команды.

Образцы кода, как всегда, можно найти на GitHub .