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

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

/* текст */

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

//текст

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

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

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

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

Что такое Javadoc?

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

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

Пример

06

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

....

используется для создания разрыва абзаца —

Пример

15 
Теги javadoc
 
 Инструмент javadoc распознает следующие теги — 
 
Тег
 
Описание
 
Синтаксис
 
 
@author
 
Добавляет автора класса.
 
@имя автора-текст
 
 
{@code}
 
Отображает текст кодовым шрифтом без интерпретации текста как HTML-разметки или вложенных тегов javadoc.
 
{@code text}
 
 
{@docRoot}
 
Представляет относительный путь к корневому каталогу сгенерированного документа с любой сгенерированной страницы.
 
{@docRoot}
 
 
@deprecated
 
Добавляет комментарий, указывающий, что этот API больше не следует использовать.
 
@deprecated deprecatedtext
 
 
@exception
 
Добавляет броски подзаголовок к созданной документации с именем класса и текстом описания.
 
описание имени класса @exception
 
 
{@inheritDoc}
 
Наследует комментарий от ближайшего наследуемый класс или реализуемый интерфейс.
 
Наследует комментарий от непосредственного суперкласса.
 
 
{@link}
 
Вставляет встроенную ссылку с видимой текстовой меткой, которая указывает на документацию для указанного пакета, класса или имени члена ссылочного класса.
 
{@link package.class#member label}
 
 
{@linkplain}
 
Идентичен {@link}, за исключением того, что метка ссылки отображается обычным текстом, а не кодовым шрифтом.
 
{@linkplain package.class#member label}
 
 
@param
 
Добавляет параметр с указанным именем параметра, за которым следует указанное описание, в раздел «Параметры».
 
описание имени параметра @param
 
 
@return
 
Добавляет раздел "Возврат" с текстом описания.
 
@return description
 
 
@see
 
Добавляет заголовок "См. также" со ссылкой или текстовой записью, указывающей на ссылку.
 
@см. ссылку
 
 
@serial
 
Используется в комментарии документа для сериализуемого поля по умолчанию.
 
@serial field-description | включить | исключить
 
 
@serialData
 
Документирует данные, записанные методами writeObject() или writeExternal().
 
@serialData data-description
 
 
@serialField
 
Документирует компонент ObjectStreamField.
 
@serialField имя-поля тип-поля описание-поля
 
 
@since
 
Добавляет заголовок «С тех пор» с указанным текстом «с тех пор» в сгенерированную документацию.
 
@с момента выпуска
 
 
@throws
 
Теги @throws и @exception являются синонимами.
 
@throws выдает описание имени класса
 
 
{@value}
 
Когда {@value} используется в комментарии статического поля, отображается значение этой константы.
 
{@value package.class#field}
 
 
@версия
 
Добавляет подзаголовок «Версия» с указанным текстом версии к сгенерированным документам при использовании параметра -version.
 
@version version-text
 
 
 
Пример
 
 Следующая программа использует несколько важных тегов, доступных для комментариев к документации. Вы можете использовать другие теги в зависимости от ваших требований.
 
 Документация по классу AddNum будет создана в HTML-файле AddNum.html, но в то же время будет создан мастер-файл с именем index.html.
 
22
 
 Теперь обработайте вышеуказанный файл AddNum.java с помощью утилиты javadoc следующим образом — 
 
36
 
 Вы можете проверить всю сгенерированную документацию здесь — AddNum. Если вы используете JDK 1.7, javadoc не создает отличный stylesheet.css. , поэтому мы предлагаем загрузить и использовать стандартную таблицу стилей с https://docs.oracle.com/javase/7/docs/api/stylesheet.css
 

            


            

               Java — Основы апплетов         
                Java 10 — Обзор