Учебники

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

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

Sr.No. Комментарий и описание
1

/ * текст * /

Компилятор игнорирует все от / * до * /.

2

//текст

Компилятор игнорирует все от // до конца строки.

3

/** документация */

Это комментарий к документации и в целом его называют комментарием к документу . Инструмент JDK Javadoc использует комментарии к документам при подготовке автоматически сгенерированной документации.

/ * текст * /

Компилятор игнорирует все от / * до * /.

//текст

Компилятор игнорирует все от // до конца строки.

/** документация */

Это комментарий к документации и в целом его называют комментарием к документу . Инструмент JDK Javadoc использует комментарии к документам при подготовке автоматически сгенерированной документации.

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

Что такое Javadoc?

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

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

пример

/**
* The HelloWorld program implements an application that
* simply displays "Hello World!" to the standard output.
*
* @author  Zara Ali
* @version 1.0
* @since   2014-03-31 
*/
public class HelloWorld {

   public static void main(String[] args) {
      /* Prints Hello, World! on standard output.
      System.out.println("Hello World!");
   }
}

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

пример

/**
* <h1>Hello, World!</h1>
* The HelloWorld program implements an application that
* simply displays "Hello World!" to the standard output.
* <p>
* Giving proper comments in your program makes it more
* user friendly and it is assumed as a high quality code.
* 
*
* @author  Zara Ali
* @version 1.0
* @since   2014-03-31 
*/
public class HelloWorld {

   public static void main(String[] args) {
      /* Prints Hello, World! on standard output.
      System.out.println("Hello World!");
   }
}

Теги Javadoc

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

Тег Описание Синтаксис
@author Добавляет автора класса. @ имя автора текста
{@код} Отображает текст с использованием шрифта кода без интерпретации текста как разметки HTML или вложенных тегов Javadoc. {@ code text}
{} @DocRoot Представляет относительный путь к корневому каталогу сгенерированного документа с любой сгенерированной страницы. {} @DocRoot
@deprecated Добавляет комментарий, указывающий, что этот API больше не должен использоваться. @deprecated deprecatedtext
@exception Добавляет подзаголовок Throws к сгенерированной документации с именем класса и текстом описания. @exception class-name description
{} @InheritDoc Наследует комментарий от ближайшего наследуемого класса или реализуемого интерфейса. Наследует комментарий от непосредственного суперкласса.
{@ссылка на сайт} Вставляет встроенную ссылку с видимой текстовой меткой, которая указывает на документацию для указанного пакета, класса или имени члена ссылочного класса. {@link package.class # метка участника}
{} @Linkplain Идентичен {@link}, за исключением того, что ярлык ссылки отображается в виде обычного текста, а не шрифта кода. {@linkplain package.class # метка участника}
@param Добавляет параметр с указанным именем параметра, за которым следует указанное описание, в раздел «Параметры». @param имя параметра описание
@вернуть Добавляет раздел «Возвраты» с текстом описания. @ возвращение описание
@увидеть Добавляет заголовок «Смотрите также» со ссылкой или текстовой записью, которая указывает на ссылку. @ см. ссылку
@serial Используется в комментарии к документу для сериализуемого поля по умолчанию. @serial field-description | включить | исключать
@serialData Документирует данные, записанные методами writeObject () или writeExternal (). @serialData data-description
@serialField Документирует компонент ObjectStreamField. @serialField field-name field-type field-description
@поскольку Добавляет заголовок «С» с указанным текстом текста в созданную документацию. @ релиз
@throws Теги @throws и @exception являются синонимами. @ бросает описание имени класса
{@значение} Когда {@value} используется в комментариях к документу статического поля, он отображает значение этой константы. {@value package.class # field}
@версия Добавляет подзаголовок «Версия» с указанным текстом версии в сгенерированные документы, когда используется опция -version. @ версия-текст версии

пример

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

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

import java.io.*;

/**
* <h1>Add Two Numbers!</h1>
* The AddNum program implements an application that
* simply adds two given integer numbers and Prints
* the output on the screen.
* <p>
* <b>Note:</b> Giving proper comments in your program makes it more
* user friendly and it is assumed as a high quality code.
*
* @author  Zara Ali
* @version 1.0
* @since   2014-03-31
*/
public class AddNum {
   /**
   * This method is used to add two integers. This is
   * a the simplest form of a class method, just to
   * show the usage of various javadoc Tags.
   * @param numA This is the first paramter to addNum method
   * @param numB  This is the second parameter to addNum method
   * @return int This returns sum of numA and numB.
   */
   public int addNum(int numA, int numB) {
      return numA + numB;
   }

   /**
   * This is the main method which makes use of addNum method.
   * @param args Unused.
   * @return Nothing.
   * @exception IOException On input error.
   * @see IOException
   */

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

      System.out.println("Sum of 10 and 20 is :" + sum);
   }
}

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

$ javadoc AddNum.java
Loading source file AddNum.java...
Constructing Javadoc information...
Standard Doclet version 1.7.0_51
Building tree for all the packages and classes...
Generating /AddNum.html...
AddNum.java:36: 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...
1 warning
$

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