Java - Комментарии к документации
Язык Java поддерживает три типа комментариев:
| Sr. No. | Комментарий и описание |
|---|---|
| 1 | /* text */ Компилятор игнорирует все от / * до * /. |
| 2 | //text Компилятор игнорирует все от // до конца строки. |
| 3 | /** documentation */ Это комментарий к документации, и в целом он называется doc comment. В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 | Добавляет автора класса. | @author имя-текст |
| {@код} | Отображает текст шрифтом кода без интерпретации текста как разметки HTML или вложенных тегов javadoc. | {@code text} |
| {@docRoot} | Представляет относительный путь к корневому каталогу сгенерированного документа от любой сгенерированной страницы. | {@docRoot} |
| @deprecated | Добавляет комментарий, указывающий, что этот API больше не следует использовать. | @deprecated deprecatedtext |
| @exception | Добавляет Throws подзаголовок сгенерированной документации с именем класса и текстом описания. | @exception описание имени класса |
| {@inheritDoc} | Наследует комментарий от nearest наследуемый класс или реализуемый интерфейс. | Наследует комментарий от непосредственного суперкласса. |
| {@ссылка} | Вставляет встроенную ссылку с видимой текстовой меткой, которая указывает на документацию для указанного пакета, класса или имени члена указанного класса. | {@link package.class # member label} |
| {@linkplain} | Идентично {@link}, за исключением того, что подпись ссылки отображается в виде обычного текста, а не шрифта кода. | {@linkplain package.class # member label} |
| @param | Добавляет параметр с указанным именем параметра, за которым следует указанное описание, в раздел «Параметры». | @param описание имени параметра |
| @возвращение | Добавляет раздел «Возврат» с текстом описания. | @return описание |
| @видеть | Добавляет заголовок «См. Также» со ссылкой или текстовой записью, указывающей на ссылку. | @ см. ссылку |
| @serial | Используется в комментарии к документу для сериализуемого поля по умолчанию. | @serial field-description | включить | исключить |
| @serialData | Документирует данные, записанные методами writeObject () или writeExternal (). | @serialData описание данных |
| @serialField | Документирует компонент ObjectStreamField. | @serialField имя-поля тип поля описание-поля |
| @поскольку | Добавляет заголовок «Since» с указанным текстом «Since» в созданную документацию. | @ с момента выпуска |
| @throws | Теги @throws и @exception являются синонимами. | @throws описание имени класса |
| {@значение} | Когда {@value} используется в комментарии к документу статического поля, он отображает значение этой константы. | {@value package.class # field} |
| @версия | Добавляет подзаголовок «Версия» с указанным текстом версии в сгенерированные документы при использовании параметра -version. | @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