1. Обзор
Хорошая документация по API - один из многих факторов, способствующих общему успеху программного проекта.
К счастью, все современные версии JDK предоставляют инструмент Javadoc - для генерации документации API из комментариев, присутствующих в исходном коде.
Предпосылки:
, JDK 1.4 (JDK 7 рекомендуется для последней версии Maven
Плагин Javadoc) , Папка JDK /bin , добавленная в переменную среды PATH
, (Необязательно) IDE со встроенными инструментами
Давайте начнем с комментариев.
-
Структура комментариев Javadoc выглядит очень похоже на обычный многострочный комментарий ** , но ключевым отличием является дополнительная звездочка в начале:
----//This is a single line comment
/**
** This is a regular multi-line comment
** //** **
** This is a Javadoc
** /-----
Комментарии в стиле Javadoc также могут содержать теги HTML. **
2.1. Javadoc формат
-
Комментарии Javadoc могут быть размещены над любым классом, методом или полем, которое мы хотим задокументировать. **
Эти комментарии обычно состоят из двух разделов:
, Описание того, что мы комментируем
, Теги автономного блока (помеченные символом « @ »), которые
описать конкретные метаданные
Мы будем использовать некоторые из наиболее распространенных тегов блоков в нашем примере. Полный список тегов блоков см. В reference guide .
2.2. Javadoc на уровне класса
Давайте посмотрим, как будет выглядеть комментарий Javadoc на уровне класса:
----/** **
** Hero is the main entity we'll be using to . . .
**
** Please see the {@link com.baeldung.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;
}
----Метод successfullyAttacked содержит описание и многочисленные автономные теги блоков.
Существует множество блочных тегов, помогающих создать правильную документацию, и мы можем включать в себя всевозможные виды информации. Мы можем даже использовать базовые теги HTML в комментариях.
Давайте рассмотрим теги, с которыми мы сталкиваемся в примере выше:
-
@ param предоставляет любое полезное описание параметра метода или
вход следует ожидать ** @ return предоставляет описание того, что метод может или может вернуть
-
@ see создаст ссылку, аналогичную тегу \ {@ link} , но более подробно
контекст ссылки, а не встроенный ** @ since указывает, какая версия класса, поля или метода была добавлена
к проекту ** @ version указывает версию программного обеспечения, обычно используемую с
Макросы% I% и% G% ** @ throws используется для дальнейшего объяснения случаев, когда программное обеспечение
ожидать исключения ** @ deprecated дает объяснение, почему код устарел, когда он
возможно, устарели, и каковы альтернативы
Хотя оба раздела технически необязательны, нам потребуется хотя бы один раздел, чтобы инструмент Javadoc мог генерировать что-либо значимое.
3. Поколение Javadoc
Чтобы сгенерировать наши страницы Javadoc, мы хотим взглянуть на инструмент командной строки, который поставляется вместе с JDK, и плагин Maven.
3.1. Инструмент командной строки Javadoc
Инструмент командной строки Javadoc является очень мощным, но имеет некоторую сложность.
Выполнение команды javadoc без каких-либо параметров или параметров приведет к ошибке и ожидаемым выходным параметрам.
Нам нужно по крайней мере указать, для какого пакета или класса мы хотим, чтобы документация была сгенерирована.
Давайте откроем командную строку и перейдем в каталог проекта.
Предполагая, что все классы находятся в папке src в каталоге проекта:
----[email protected]:~$ 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>В базовом каталоге проекта мы запускаем команду для генерации наших Javadoc в каталог в target \ site:
----[email protected]:~$ mvn javadoc:javadoc
----The модуль Maven очень мощный и облегчает создание сложных документов.
Давайте теперь посмотрим, как выглядит сгенерированная страница Javadoc:
ссылка:/uploads/overview-125x125.png%20125w[]
Мы можем увидеть древовидное представление классов, которые расширяет наш класс SuperHero . Мы можем увидеть наше описание, поля и метод, и мы можем нажать на ссылки для получения дополнительной информации.
Детальный вид нашего метода выглядит так:
ссылка:/uploads/ss__javadoc-1024x579-768x434.png%20768w[]
3.3. Пользовательские теги Javadoc
В дополнение к использованию предопределенных тегов блоков для форматирования нашей документации мы также можем создавать собственные теги блоков.
Для этого нам просто нужно включить параметр -tag в нашу командную строку Javadoc в формате <tag-name>: <местоположения-разрешено>: <заголовок> .
Чтобы создать собственный тег с именем @ location , разрешенный в любом месте, который отображается в заголовке «Известные расположения» в нашем сгенерированном документе, нам нужно выполнить:
----[email protected]:~$ 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 и выполнить соответствующие команды.
Примеры кода, как всегда, можно найти по адресу over на GitHub .