Комментарии документации Java

Java поддерживает три стиля комментариев:

  • Однострочные комментарии
  • Многострочные комментарии
  • Документирующие комментарии

Первые два — это соответственно//и/* */, третий тип называется документационными комментариями, он начинается/**с открывающего разделителя и заканчивается*/закрывающим разделителем.

Для первых двух типов комментариев можно обратиться к следующему:Комментарии Java

Документационные комментарии позволяют встраивать информацию о вашей программе в саму программу.

Вы можете использовать инструмент javadoc, чтобы сгенерировать информацию и вывести её в HTML-файл.

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

Теги javadoc

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

Тег Описание Пример
@author Определяет автора класса @author описание
@deprecated Указывает на устаревший класс или член @deprecated описание
{@docRoot} Указывает путь к текущему корневому каталогу документа Путь к каталогу
@exception Документирует исключение, выбрасываемое классом @exception exception-name пояснение
{@inheritDoc} Наследует комментарий от непосредственного родительского класса Наследует комментарий от непосредственного суперкласса.
{@link} Вставляет ссылку на другую тему {@link name text}
{@linkplain} Вставляет ссылку на другую тему, но ссылка отображается обычным текстовым шрифтом Вставляет встроенную ссылку на другую тему.
@param Описывает параметр метода @param parameter-name описание
@return Описывает тип возвращаемого значения @return описание
@see Задает ссылку на другую тему @see якорь
@serial Описывает свойство сериализации @serial описание
@serialData Описывает данные, записываемые с помощью методов writeObject( ) и writeExternal( ) @serialData описание
@serialField Описывает компонент ObjectStreamField @serialField имя тип описание
@since Отмечает, когда было внесено конкретное изменение @since release
@throws То же, что и тег @exception. Тег @throws имеет то же значение, что и тег @exception.
{@value} Отображает значение константы, которая должна быть статическим атрибутом. Отображает значение константы, которая должна быть статическим полем.
@version Указывает версию класса @version info

Комментарии документации

После открывающего/**первая строка или строки — это основное описание класса, переменной или метода.

После этого можно включить один или несколько различных@тегов. Каждый@тег должен находиться в начале новой строки или сразу следовать за звёздочкой в начале строки*。

Несколько тегов одного типа следует группировать вместе. Например, если у вас есть три@seeтега, вы можете разместить их один за другим.

Ниже приведён пример комментария класса:

/*** Этот класс рисует столбчатую диаграмму * @author example * @version 1.2 */

Что выводит javadoc

Инструмент javadoc принимает исходный код вашей Java-программы в качестве входных данных и выводит HTML-файлы, содержащие комментарии вашей программы.

Информация о каждом классе будет в отдельном HTML-файле. javadoc также может выводить структуры дерева наследования и индексы.

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

Пример

Ниже приведён простой пример использования комментариев документации. Обратите внимание, что каждый комментарий появляется перед элементом, который он описывает.

После обработки с помощью javadoc комментарий класса SquareNum будет найден в SquareNum.html.

Код файла SquareNum.java:

import java.io.*; /** * Этот класс демонстрирует документирующие комментарии * @author Ayan Amhed * @version 1.2 */ public class SquareNum { /** * Этот метод возвращает квадрат num. * Это многострочное описание. Вы можете использовать * столько строк, сколько пожелаете. * @param num Значение, которое нужно возвести в квадрат. * @return num в квадрате. */ public double square(double num) { return num * num; } /** * Этот метод считывает число, введённое пользователем. * @return Значение, введённое как double. * @exception IOException При ошибке ввода. * @see IOException */ public double getNumber() throws IOException { InputStreamReader isr = new InputStreamReader(System.in); BufferedReader inData = new BufferedReader(isr); String str; str = inData.readLine(); return (new Double(str)).doubleValue(); } /** * Этот метод демонстрирует square(). * @param args Не используется. * @return Ничего. * @exception IOException При ошибке ввода. * @see IOException */ public static void main(String args[]) throws IOException { SquareNum ob = new SquareNum(); double val; System.out.println("Введите значение для возведения в квадрат: "); val = ob.getNumber(); val = ob.square(val); System.out.println("Значение в квадрате равно " + val); } }

Как показано ниже, используйте инструмент javadoc для обработки файла SquareNum.java:

$ javadoc SquareNum.java
Loading source file SquareNum.java...
Constructing Javadoc information...
Standard Doclet version 1.5.0_13
Building tree for all the packages and classes...
Generating SquareNum.html...
SquareNum.java:39: warning - @return tag cannot be used\
                      in method with void return type.
Generating package-frame.html...
Generating package-summary.html...
Generating package-tree.html...
Generating constant-values.html...
Building index for all the packages and classes...
Generating overview-tree.html...
Generating index-all.html...
Generating deprecated-list.html...
Building index for all classes...
Generating allclasses-frame.html...
Generating allclasses-noframe.html...
Generating index.html...
Generating help-doc.html...
Generating stylesheet.css...
1 warning
$
Другие расширения