Язык Java поддерживает три типа комментариев:

№ и описание
1/* текст */
Компилятор игнорирует все от / * до * /.
2//текст
Компилятор игнорирует все от // до конца строки.
3/** документация */
Это документационный комментарий. Инструмент JDK (комплект разработчика приложений на языке Java) javadoc использует документационные комментарии при подготовке автоматически созданной документации.

Эта глава посвящена как пользоваться Javadoc. Мы посмотрим, как мы можем использовать Javadoc для создания полезной документации для кода Java.

Что такое Javadoc?

Javadoc – это инструмент, который поставляется с JDK и используется для создания документации кода Java в формате HTML из исходного кода Java, для чего требуется документация в заранее определенном формате.

Ниже приводится простой пример, в котором строки внутри /*….*/ представляют собой многострочные комментарии Java. Точно так же строка, предшествующая //, является однострочным комментарием Java.

Пример 1

/**
* Программа HelloWorld реализует приложение, которое
* выводит "Привет, Мир!" на стандартном потоке вывода.
*
* @автор Zara Ali
* @версия 1.0
* @от   2014-03-31 
*/
public class HelloWorld {

   public static void main(String[] args) {
      // Выводит "Привет, Мир!" на стандартном потоке вывода.
      System.out.println("Привет, Мир!");
   }
}

Вы можете включить необходимые HTML-теги внутри части описания. Например, в следующем примере используется <h1> .... </h1> для заголовка, а <p> используется для создания разрыва абзаца.

Пример 2

/**
* <h1> Привет, Мир!</h1>
* Программа HelloWorld реализует приложение, которое
* выводит "Привет, Мир!" на стандартном потоке вывода.
* <p>
* Правильные комментарии в вашей программе делают ее более
* удобной для пользователя и предполагается, что этот код является 
* более высококачественным.
*
* @ автор Zara Ali
* @ версия 1.0
* @ от 2014-03-31 
*/
public class HelloWorld {

   public static void main(String[] args) {
      // Выводит "Привет, Мир! " на стандартном потоке вывода.
      System.out.println("Привет, Мир!");
   }
}

Теги Javadoc

Инструмент javadoc распознает следующие теги:

Тег Описание Синтаксис
@author Добавляет автора класса. @author name-text
{@code} Отображает текст шрифтом кода без интерпретации текста как разметки HTML или вложенных тегов javadoc. {@code text}
{@docRoot} Представляет относительный путь к корневому каталогу сгенерированного документа от любой сгенерированной страницы. {@docRoot}
@deprecated Добавляет комментарий, указывающий, что этот прикладной программный интерфейс больше не следует использовать. @deprecated deprecatedtext
@exception Добавляет подзаголовок Throws в сгенерированную документацию с именем класса и текстом описания @exception class-name description
{@inheritDoc} Наследует комментарий от ближайшего наследуемого класса или реализуемого интерфейса Inherits a comment from the immediate surperclass.
{@link} Вставляет встроенную ссылку с видимой текстовой меткой, которая указывает на документацию для указанного пакета, класса или имени члена указанного класса. {@link package.class#member label}
{@linkplain} Идентично {@link}, за исключением того, что подпись ссылки отображается в виде обычного текста, а не шрифта кода. {@linkplain package.class#member label}
@param Добавляет параметр с указанным именем параметра, за которым следует указанное описание, в раздел «Параметры». @param parameter-name description
@return Добавляет раздел «Возврат» с текстом описания. @return description
@see Добавляет заголовок «Смотрите также» со ссылкой или текстовой записью, указывающей на ссылку. @see reference
@serial Используется в комментарии к документу для сериализуемого поля по умолчанию. @serial field-description | include | exclude
@serialData Документирует данные, записанные методами writeObject() или writeExternal(). @serialData data-description
@serialField Документирует компонент ObjectStreamField. @serialField field-name field-type field-description
@since Добавляет заголовок «От» с указанным текстом в созданную документацию. @since release
@throws Теги @throws и @exception являются синонимами. @throws class-name description
{@value} Когда {@value} используется в комментарии к документу статического поля, он отображает значение этой константы. {@value package.class#field}
@version Добавляет подзаголовок «Версия» с указанным текстом версии в сгенерированные документы при использовании параметра -version. @version version-text

Пример

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

Документация о классе AddNum будет создана в HTML-файле AddNum.html, но в то же время будет создан главный файл с названием index.html.

import java.io.*;

/**
* <h1> Сложите два числа!</h1>
* Программа AddNum реализует приложение, которое
* просто складывает два заданных целых числа и выводит
* результат на экран.
* <p>
* <b>Примечание:</b> Правильные комментарии в вашей программе 
* удобной для пользователя и предполагается, что этот код является 
* более высококачественным.
*
* @автор  Zara Ali
* @версия 1.0
* @от   2014-03-31
*/
public class AddNum {
   /**
   * Этот метод используется для сложения двух целых чисел. Это
   * простейшая форма метода класса, просто чтобы
   * показать использование различных тегов javadoc.
   * @param numA Это первый параметр метода addNum 
   * @param numB Это второй параметр метода addNum 
   * @return int Это возвращает сумму numA и numB.
   */
   public int addNum(int numA, int numB) {
      return numA + numB;
   }

   /**
   * Это основной метод, использующий метод addNum.
   * @param args Не используется.
   * @return Ничего.
   * @exception IOException При ошибке ввода.
   * @see IOException
   */

   public static void main(String args[]) throws IOException {
      AddNum obj = new AddNum();
      int sum = obj.addNum(10, 20);

      System.out.println("Суммой 10 и 20 является :" + sum);
   }
}

Теперь обработайте указанный выше файл AddNum.java с помощью утилиты javadoc следующим образом:

$ javadoc AddNum.java
Загрузка исходного файла AddNum.java ...
Создание информации Javadoc ...
Версии стандартного Doclet 1.7.0_51
Построение схемы в виде дерева для всех пакетов и классов ...
Создание /AddNum.html ...
AddNum.java:36: предупреждение - тег @return не может использоваться в методе с типом возврата void.
Создание /package-frame.html ...
Создание /package-summary.html ...
Создание /package-tree.html ...
Создание /constant-values.html ...
Построение индекса для всех пакетов и классов ...
Создание /overview-tree.html ...
Создание /index-all.html ...
Создание /deprecated-list.html ...
Построение индекса для всех классов ...
Создание /allclasses-frame.html ...
Создание /allclasses-noframe.html ...
Создание /index.html ...
Создание /help-doc.html ...
1 предупреждение
$

Если вы используете JDK 1.7, то javadoc не создает большой stylesheet.css, поэтому мы предлагаем загрузить и использовать стандартную таблицу стилей по ссылке https://docs.oracle.com/javase/7/docs/api/stylesheet.css

Источник: Java - Documentation Comments.

Оглавление