Рубрики
Без рубрики

Знакомство с Javadoc

Узнайте об основном использовании JavaDoc и о том, как создать HTML-файл JavaDoc.

Автор оригинала: baeldung.

1. Обзор

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

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

Необходимые условия:

  1. JDK 1.4 (JDK 7 ” рекомендуется для последней версии плагина Maven Javadoc)
  2. JDK /бин папка добавлена в PATH переменная окружающей среды
  3. (Необязательно) 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 могут быть размещены над любым классом, методом или полем, которое мы хотим задокументировать.

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

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

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

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 папка в каталоге проекта:

[email protected]:~$ javadoc -d doc src\*

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

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

3.2. Джавадок с Maven Plugin

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


    
        
            org.apache.maven.plugins
            maven-javadoc-plugin
            3.0.0
            
                1.8
                1.8
            
            
            ...
            
        
    

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

[email protected]:~$ mvn javadoc:javadoc

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

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

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

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

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

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

Для этого нам просто необходимо включить в него -тег вариант нашей командной строки Javadoc в формате ::

.

Для создания пользовательского тега под названием @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 достаточно гибок, чтобы также разрешать определения наших пользовательских тегов в наших пом.xml .

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

...

    
        location
        a
        Notable Places:
     

...

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

4. Заключение

Это краткое введение учебник охватывает, как написать основные Javadocs и генерировать их с командной строки Javadoc.

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

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