Хорошая документация API является одним из многих факторов, способствующих общему успеху программного проекта.
К счастью, все современные версии JDK предоставляют инструмент Javadoc – для создания документации API из комментариев, присутствующих в исходным коде.
Необходимые условия:
JDK 1.4 (JDK 7 ” рекомендуется для последней версии плагина Maven Javadoc)
JDK /бин папка добавлена в PATH переменная окружающей среды
(Необязательно) IDE, который со встроенными инструментами
2. Комментарии Джавадока
Начнем с комментариев.
Структура комментариев Javadoc очень похожа на обычный многослойный комментарий , но ключевым отличием является дополнительная звездочка в начале:
// This is a single line comment
/*
* This is a regular multi-line comment
*/
/**
* This is a Javadoc
*/
Комментарии в стиле Javadoc также могут содержать HTML-теги.
2.1. Формат Джавадок
Комментарии Javadoc могут быть размещены над любым классом, методом или полем, которое мы хотим задокументировать.
Эти замечания обычно состоит из двух разделов:
Описание того, что мы комментируем
Автономные теги блоков (отмеченные ” @ ” символ), которые описывают конкретные мета-данные
Мы будем использовать некоторые из наиболее распространенных тегов блока в нашем примере. Полный список тегов блоков можно получить в справочное руководство .
2.2. Джавадок на уровне класса
Давайте посмотрим, как будет выглядеть комментарий 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 ярлык
Inline теги могут появиться в любом месте и окружены фигурные скобки , например, @link тег в описании
В нашем примере мы также можем увидеть два вида тегов блоков, используемых:
(@link) предоставляет ссылку на ссылку на ссылку на часть нашего исходных кодов
@author имя автора, который добавил класс, метод или поле, которое комментируется
2.3. Джавадок на полевом уровне
Мы также можем использовать описание без каких-либо тегов блока, как это внутри нашего СуперГерой класс:
/**
* The public name of a hero that is common knowledge
*/
private String heroName;
Частные поля не будут иметь Javadoc генерируется для них, если мы явно передать -частный вариант для команды Javadoc.
2.4. Джавадок на уровне метода
Методы могут содержать различные теги блоков Javadoc.
Давайте рассмотрим метод, который мы используем:
/**
*
This is a simple description of the method. . .
* Superman!
*
* @param incomingDamage the amount of incoming damage
* @return the amount of health hero has after attack
* @see HERO-402
* @since 1.0
*/
public int successfullyAttacked(int incomingDamage) {
// do things
return 0;
}
успешноНавелась метод содержит как описание, так и многочисленные автономные теги блоков.
Там очень много тегов блока, чтобы помочь создать правильную документацию, и мы можем включить все виды различных видов информации. Мы даже можем использовать основные HTML теги в комментариях.
Давайте рассмотрим теги, с которыми мы сталкиваемся в приведенной выше примере:
@param предоставляет любое полезное описание параметра или ввода метода, которое следует ожидать
@return дает описание того, что метод будет или может вернуть
@see будет генерировать ссылку, похожую на (@link) тег, но больше в контексте ссылки, а не inline
@since определяет, какая версия класса, поля или метода была добавлена в проект
@version определяет версию программного обеспечения, обычно используемого с макросами %I% и %G%
@throws используется для дальнейшего объяснения случаев, когда программное обеспечение ожидает исключения
@deprecated дает объяснение того, почему код был deprecated, когда он, возможно, были увенены, и то, что альтернативы
Хотя оба раздела технически необязательны, нам понадобится по крайней мере один для инструмента Javadoc для создания чего-либо значимого.
3. Поколение Джавадок
Для того, чтобы создать наши страницы Javadoc, мы хотим взглянуть на инструмент командной линии, который поставляется с JDK, и плагин Maven.
3.1. Инструмент командной линии Javadoc
Инструмент командной строки Javadoc очень мощный, но имеет некоторую сложность, прилагаемую к нему.
Запуск командного Джавадок без каких-либо вариантов или параметров приведет к ошибке и выход параметров он ожидает.
Нам нужно, по крайней мере, указать, для какого пакета или класса мы хотим получить документацию.
Давайте откроем командную строку и перейдите к каталогу проекта.
Предполагая, что классы все в src папка в каталоге проекта:
Это позволит создать документацию в каталоге под названием Док как указано в – d флаг. Если существует несколько пакетов или файлов, мы должны предоставить все из них.
Использование IDE со встроенной функциональностью, конечно, проще и в целом рекомендуется.
Maven плагин является очень мощным и облегчает сложное производство документов бесшовно.
Давайте теперь посмотрим, как выглядит созданная страница Javadoc:
Мы можем увидеть вид на дерево классов нашей СуперГерой класс расширяется. Мы можем видеть наше описание, поля и метод, и мы можем нажать на ссылки для получения дополнительной информации.
Детальное представление нашего метода выглядит так:
3.3. Пользовательские теги Javadoc
В дополнение к использованию предопределенных тегов блока для форматирования нашей документации, мы также можем создавать пользовательские теги блоков.
Для этого нам просто необходимо включить в него -тег вариант нашей командной строки Javadoc в формате :: .
Для создания пользовательского тега под названием @location разрешено в любом месте, которое отображается в заголовке “Знатные места” в нашем сгенерированном документе, мы должны запустить:
Для того, чтобы использовать этот тег, мы можем добавить его в раздел блока комментария Javadoc:
/**
* This is an example...
* @location New York
* @returns blah blah
*/
Плагин Maven Javadoc достаточно гибок, чтобы также разрешать определения наших пользовательских тегов в наших пом.xml .
Для того, чтобы настроить тот же тег выше для нашего проекта, мы можем добавить следующее в раздел нашего плагина:
...
locationa
Notable Places:
...
Таким образом, позволяет нам указать пользовательский тег один раз, вместо того, чтобы указывать его каждый раз.
4. Заключение
Это краткое введение учебник охватывает, как написать основные Javadocs и генерировать их с командной строки Javadoc.
Более простой способ создания документации позволит использовать любые встроенные варианты IDE или включить плагин Maven в наш пом.xml файл и запустить соответствующие команды.