Javadoc

Javadoc — генератор документации в HTML-формате из комментариев исходного кода на Java от Sun Microsystems. Javadoc — стандарт для документирования классов Java. Большинство сред разработки программного обеспечения автоматически генерируют HTML-документацию, используя Javadoc.

Javadoc
Скриншот программы Javadoc
Тип Генератор документации
Разработчик Sun Microsystems
Операционная система кроссплатформенная
Аппаратная платформа Java Virtual Machine
Последняя версия 1.50
Лицензия GNU GPL 2 + «Classpath exception»[1]
Сайт docs.oracle.com/javase/8…

Javadoc также предоставляет API для создания доклетов и тэглетов, которые позволяют программисту анализировать структуру Java-приложения.


Применение

править

Комментарии документации применяют для:

  • документирования классов,
  • интерфейсов,
  • полей (переменных),
  • конструкторов,
  • методов,
  • пакетов.

В каждом случае комментарий должен находиться перед документируемым элементом.

Список дескрипторов Javadoc
Дескриптор Описание Применим к
@author Автор класс, интерфейс
@version Версия. Не более одного дескриптора на класс класс, интерфейс
@since Указывает, с какой версии доступно класс, интерфейс, поле, метод
@see Ссылка на другое место в документации класс, интерфейс, поле, метод
@param Входной параметр метода метод
@return Описание возвращаемого значения метод
@exception имякласса описание
@throws имякласса описание
Описание исключения, которое может быть послано из метода метод
@deprecated Описание устаревших блоков кода класс, интерфейс, поле, метод
{@link reference} Ссылка класс, интерфейс, поле, метод
{@value} Описание значения переменной статичное поле


Для документирования переменной можно использовать следующие дескрипторы: @see, @serial, @serialField, {@value}, @deprecated. Для классов и интерфейсов можно использовать дескрипторы: @see, @author, @deprecated, @param, @version. Методы можно документировать с помощью дескрипторов: @see, @return, @param, @deprecated, @throws, @serialData, {@inheritDoc}, @exception.

Дескрипторы {@link}, {@docRoot}, {@code}, {@literal}, @since, {@linkplain} могут применяться где угодно.

Пример

править

Пример использования разметки Javadoc для документирования метода [2]. Типы переменных указывать не нужно.

 /**
  * <p>Проверяет, допустимый ли ход.</p>
  * <p>Например, чтобы задать ход e2-e4, напишите isValidMove(5,2,5,4);
  * Чтобы записать рокировку, укажите, откуда и куда ходит король.
  * Например, для короткой рокировки чёрных запишите isValidMove(5,8,7,8);</p>
  *
  * @param fromCol Вертикаль, на которой находится фигура (1=a, 8=h)
  * @param fromRow Горизонталь, на которой находится фигура (1...8)
  * @param toCol   Вертикаль клетки, на которую выполняется ход (1=a, 8=h)
  * @param toRow   Горизонталь клетки, на которую выполняется ход (1...8)
  * @return true, если ход допустим, и false, если недопустим
  */
  boolean isValidMove(int fromCol, int fromRow, int toCol, int toRow) {
      . . .
  }

См. также

править

Примечания

править
  1. Free and Open Source Java — FAQ (англ.). Дата обращения: 3 февраля 2010. Архивировано из оригинала 3 марта 2012 года.
  2. How to Write Doc Comments for the Javadoc Tool. Дата обращения: 15 марта 2011. Архивировано 29 апреля 2020 года.

Ссылки

править

Статьи

править