Введение в Javadoc

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:

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

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

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 .