Введение в Javadoc

1. Обзор

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

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

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

  1. JDK 1.4 (для последней версии плагина Maven Javadoc рекомендуется JDK 7+)
  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.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 сгенерированного для них , если мы явно не передать -собственной опцию в команде Javadoc.

2.4. Документация Javadoc на уровне метода

Методы могут содержать множество тегов блоков 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; }

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

We can also make use of the Maven Javadoc plugin:

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

In the base directory of the project, we run the command to generate our Javadocs to a directory in target\site:

[email protected]:~$ mvn javadoc:javadoc

The Maven plugin is very powerful and facilitates complex document generation seamlessly.

Let's now see what a generated Javadoc page looks like:

We can see a tree view of the classes our SuperHero class extends. We can see our description, fields, and method, and we can click on links for more information.

A detailed view of our method looks like this:

3.3. Custom Javadoc Tags

In addition to using predefined block tags to format our documentation, we can also create custom block tags.

In order to do so, we just need to include a -tag option to our Javadoc command line in the format of ::.

In order to create a custom tag called @location allowed anywhere, which is displayed in the “Notable Locations” header in our generated document, we need to run:

[email protected]:~$ javadoc -tag location:a:"Notable Locations:" -d doc src\*

In order to use this tag, we can add it to the block section of a Javadoc comment:

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

The Maven Javadoc plugin is flexible enough to also allow definitions of our custom tags in our pom.xml.

In order to set up the same tag above for our project, we can add the following to the section of our plugin:

...   location a Notable Places:   ...

This way allows us to specify the custom tag once, instead of specifying it every time.

4. Conclusion

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

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

Примеры кода, как всегда, можно найти на GitHub.