Javadoc

Javadoc

Тип	Генератор документации
Разработчик	Sun Microsystems
Операционная система	кроссплатформенная
Последняя версия	1.50
Лицензия	GNU GPL 2 + «Classpath exception»[1]
Сайт	Официальный сайт

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

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}, @ехсерtiоn.

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

Пример

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

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

См. также

• Doxygen
• Epydoc
• JSDoc
• PhpDocumentor
• Генератор документации

Примечания

1. ↑ Free and Open Source Java — FAQ  (англ.). Архивировано из первоисточника 3 марта 2012. Проверено 3 февраля 2010.
2. ↑ How to Write Doc Comments for the Javadoc Tool

Ссылки

• Официальный сайт Javadoc  (англ.)
• Java комментарии — Javadoc

Статьи

• Теория и практика Java: Мне нужно задокументировать ЭТО?
• Skipy.ru: Записки трезвого практика -> Полезное -> Создание собственных тегов javadoc