Javadoc-комментарии

  • Обыкновенный комментарий
    /* Calculates the factorial. */
    int factorial(int x) {
    …
    
  • Javadoc-комментарий
    /** Calculates the factorial. */
    public double factorial(int x) {
    …
    

Применение Javadoc-комментариев

  • Описание
    • пакетов
    • классов
    • методов
    • конструкторов
    • полей

Пример Javadoc-комментария

/**
 * Calculates the factorial. 
 * For negative numbers returns {@code 1}.
 *
 * @param x a value
 * @return the factorial of {@code x}
 */
public double factorial(int x) {

Структура Javadoc-комментария

  • Общая структура
    /**
     * Краткое описание. Основное описание
     *
     * Блок тегов
     */
    
  • Краткое описание — первое предложение
  • Полное описание — до первого блочного тега

Типы тегов

  • Блочные теги
    • Начинается с @tag и оканчивается с началом следующего тега
    • Пример
      @param x a value
  • Строчные теги
    • Ограничены фигурными скобками
    • Могут встречаться в теле блочных тегов
    • Пример
      @return the factorial of {@code x}

Тег @param

  • Описывает параметры
  • Синтаксис
    • @param <имя параметра> <описание>
  • Примеры
    • параметр метода / компонент записи
      @param x a value
    • типовой параметр
      @param <E> element type

Тег @return

  • Описывает возвращаемое значение метода
  • Синтаксис
    • @return <описание>
  • Пример
    • @return the factorial of {@code x}

Тег @throws

  • Описывает исключения, генерируемые методом/конструктором
  • Синтаксис
    • @throws <класс исключения> <описание>
  • Пример
    • @throws IllegalArgumentException 
      if {@code x} is less than zero
      

Тег @see

  • Ссылка на дополнительную информацию
  • Синтаксис
    • @see <имя класса>
    • @see [<имя класса>]#<имя члена>
    • @see "<Текст ссылки>"
  • Примеры
    • @see Math#PI
    • @see Math#abs(int)
    • @see "The Java Programming Language 
      Specification, Chapter 17"
      

Тег @version

  • Текущая версия класса/пакета
  • Синтаксис
    • @version <описание версии>
  • Пример
    • @version 21

Тег @since

  • Версия в которой была добавлена описываемая сущность
  • Синтаксис
    • @since <описание версии>
  • Пример
    • @since 5.0

Тег @deprecated

  • Помечает возможности, которые не следует использовать
  • Синтаксис
    • @deprecated <комментарий>
  • Пример
    • @deprecated replaced by {@link #setVisible(boolean)}

Тег @author

  • Описывает автора класса/пакета
  • Синтаксис
    • @author <имя автора>
  • Пример
    • @author  Joshua Bloch
      @author  Neal Gafter
      

Тег {@link}

  • Ссылка на другую сущность
  • Синтаксис
    • {@link <класс>#<член> <текст>}
  • Примеры
    • {@link java.lang.Math#log10(double) Decimal logarithm}
    • {@link Math}
    • {@link Math#PI}
    • {@link #factorial() calculates factorial}
    • {@link java.util Collections framework}

Тег {@docRoot}

  • Заменяется на ссылку на корень документации
  • Синтаксис
    • {@docRoot}
  • Пример
    • <a href="{@docRoot}/copyright.html">Copyright</a>

Тег {@value}

  • Заменяется на значение константного поля
  • Синтаксис
    • {@value <имя класса>#<имя поля>}
  • Пример
    • Default value is {@value #DEFAULT_TIME}

Тег {@code}

  • Предназначен для вставки фрагментов кода
  • Внутри тега HTML не распознается
  • Синтаксис
    • {@code <код>}
  • Пример
    • Is equivalent of {@code Collection<E>}.

Применение Javadoc

Содержание

К чему могут применяться теги

ПакетыКлассыМетоды и конструкторыПоля
@see, @since, {@link}, {@docRoot}
@deprecated
@param@value
@author, @version@return, @throws

Описание пакета

  • Файл package-info.java
    • Может содержать аннотации
  • Файл package.html в этом пакете
    • Описание – элемент <body>

Наследование Javadoc

  • Если какая-то часть информации о методе не указана, то описание копируется у ближайшего предка
  • Копируемая информация
    • Описание
    • @param
    • @returns
    • @throws

Компиляция Javadoc

Содержание

Компиляция Javadoc

  • Инструмент
    • Javadoc
  • Применение
    • javadoc <опции> <список пакетов> <список файлов>
  • Пример
    • javadoc JavadocExample1.java

Основные опции Javadoc

-sourcepath <path>Местоположения исходных файлов
-classpath <path>Местоположения используемых классов
-d <dir>Каталог для документации
-publicПодробность информации
-protected
-package
-private
-versionИнформация о версии
-authorИнформация об авторе

Ссылки

Вопросы

???