Javadoc

Java Advanced
Javadoc
Содержание
1.
2.
3.
4.
5.
6.
Структура Javadoc
Блочные тэги
Строчные тэги
Применение Javadoc
Компиляция Javadoc
Заключение
Georgiy Korneev
Java Advanced / Javadoc
2
Что такое Javadoc



Способ документирования программ
Инструмент для генерирования
документации
Сгенерированная документация
Georgiy Korneev
Java Advanced / Javadoc
3
Часть 1
Структура Javadoc
Javadoc-комментарии

Обыкновенный комментарий
/* Calculates the factorial */
int factorial(int x) {
…

Javadoc-комментарий
/** Calculates the factorial */
public double factorial(int x) {
…
Georgiy Korneev
Java Advanced / Javadoc
5
Применение Javadoc-комментариев

Описание





пакетов
классов
методов
конструкторов
полей
Georgiy Korneev
Java Advanced / Javadoc
6
Структура Javadoc-комментария
/**
* Краткое описание. Основное описание
*
* Блок тегов
*/
Georgiy Korneev
Java Advanced / Javadoc
7
Пример Javadoc-комментария
/**
* Calculates the factorial. For negative numbers
* returns <tt>1</tt>.
*
* @param x a value
* @return the factorial of <code>a</code>
*/
public double factorial(int x) {
Georgiy Korneev
Java Advanced / Javadoc
8
Типы тегов

Блочные теги


Начинается с @tag и оканчивается с началом
следующего тега
Пример
@param x a value

Строчные теги



Ограничены фигурными скобками
Могут встречаться в теле других тегов
Пример
Use a {@link java.lang.Math#log} for positive numbers.
Georgiy Korneev
Java Advanced / Javadoc
9
Часть 2
Блочные теги
Тег @param
Описавает параметров методов и
конструкторов
 Синтаксис

@param <имя параметра> <описание>

Пример
@param x a value
Georgiy Korneev
Java Advanced / Javadoc
11
Тег @return
Описывает возвращаемое значение
метода
 Синтаксис

@return <описание>

Пример
@return the factorial of <code>x</code>
Georgiy Korneev
Java Advanced / Javadoc
12
Тег @throws
Описывает исключения, генерируемые
методом/конструктором
 Синтаксис

@throws <класс исключения> <описание>

Пример
@throws IllegalArgumentException if
<code>x</code> is less than zero
Georgiy Korneev
Java Advanced / Javadoc
13
Тэг @see


Ссылка на дополнительную информацию
Синтаксис




@see <имя класса>
@see [<имя класса>]#<имя члена>
@see "<Текст ссылки>"
Примеры


@see Math#log10
@see "The Java Programming language
Specifiecation, p. 142"
Georgiy Korneev
Java Advanced / Javadoc
14
Тэг @version


Текущая версия класса/пакета
Синтаксис
@version <описание версии>

Пример
@version 5.0
Georgiy Korneev
Java Advanced / Javadoc
15
Тег @since
Версия в которой была добавлена
описываемая сущность
 Синтаксис

@since <описание версии>

Пример
@since 5.0
Georgiy Korneev
Java Advanced / Javadoc
16
Тэг @deprecated
Помечает возможности, которые не
следует использовать
 Синтаксис

@deprecated <комментарий>

Пример
@deprecated replaced by {@link #setVisible}
Georgiy Korneev
Java Advanced / Javadoc
17
Тэг @author


Описывает автора класса/пакета
Синтаксис


@author <имя автора>
Пример
@author Josh Bloch
@author Neal Gafter
Georgiy Korneev
Java Advanced / Javadoc
18
Часть 3
Строчные теги
Тэг {@link}


Ссылка на другую сущность
Синтаксис
{@link <класс>#<член> <текст>}

Примеры




{@link java.lang.Math#Log10 Decimal Logarithm}
{@link Math}
{@link Math#Log10}
{@link #factorial() calculates factorial}
Georgiy Korneev
Java Advanced / Javadoc
20
Тэг {@docRoot}
Заменяется на ссылку на корень
документации
 Синтаксис

{@docRoot}

Пример
<a href="{@docRoot}/copyright.html">Copyright</a>
Georgiy Korneev
Java Advanced / Javadoc
21
Тэг {@value}


Заменяется на значение поля
Синтаксис
{@value <имя класса>#<имя поля>}

Пример
Default value is {@value #DEFAULT_TIME}
Georgiy Korneev
Java Advanced / Javadoc
22
Тэг {@code}
Предназначен для вставки фрагментов
кода
 Внутри тэга HTML не распознается
 Синтаксис

{@code <код>}

Пример
Is equivalent of {@code Math.max(a, b)}.
Georgiy Korneev
Java Advanced / Javadoc
23
Часть 4
Применение Javadoc
Где могут быть использованы тэги
Пакеты
Классы
@author
@version
Georgiy Korneev
Методы и
конструкторы
@see
@since
{@link}
{@docRoot}
@deprecated
@param
@return
@throws
Java Advanced / Javadoc
Поля
{@value}
25
Описание пакета
Хранится в файле package.html в этом
пакете
 Описание – часть заключенная в теги
<body></body>

Georgiy Korneev
Java Advanced / Javadoc
26
Наследование Javadoc


Если какая-то часть информации о методе
не указана, то описание копируется у
ближайшего предка
Копируемая информация




Описание
@param
@returns
@throws
Georgiy Korneev
Java Advanced / Javadoc
27
Часть 5
Компиляция Javadoc
Компиляция Javadoc

Инструмент
Javadoc

Применение


javadoc <опции> <список пакетов> <список
файлов>
Пример

javadoc JavadocExample1.java
Georgiy Korneev
Java Advanced / Javadoc
29
Основные опции Javadoc
-sourcepath <path> Местоположения исходных
фалов
-classpath <path>
Местоположение
используемых классов
-d <dir>
Каталог для документации
-public
Подробность информации
-protected
-package
-private
-version
Информация о версии
-author
Информация об авторе
Georgiy Korneev
Java Advanced / Javadoc
30
Часть 6
Заключение
Ссылки



Javadoc Tool //
http://java.sun.com/j2se/1.5.0/docs/guide/java
doc/index.html
How to Write Doc Comments for the Javadoc
Tool //
http://java.sun.com/j2se/javadoc/writingdocco
mments/index.html
Javadoc FAQ //
http://java.sun.com/j2se/javadoc/faq/index.ht
ml
Georgiy Korneev
Java Advanced / Javadoc
32
Вопросы
Georgiy Korneev
Java Advanced / Javadoc
33