Javadoc — генератор документации в HTML-формате из комментариев исходного кода на Java от Sun Microsystems. Javadoc — стандарт для документирования классов Java. Большинство сред разработки программного обеспечения автоматически генерируют 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}, @exception.
Дескрипторы {@link}, {@docRoot}, {@code}, {@literal}, @since, {@linkplain} могут применяться где угодно.
Пример
Пример использования разметки Javadoc для документирования метода . Типы переменных указывать не нужно.
/** * <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) { . . .
См. также Doxygen Epydoc JSDoc PhpDocumentor Генератор документации
Примечания
Ссылки Официальный сайт Javadoc Java комментарии — Javadoc javadoc - Генератор Документации API Java
Статьи Теория и практика Java: Мне нужно задокументировать ЭТО? Skipy.ru: Записки трезвого практика -> Полезное -> Создание собственных тегов javadoc
Категория:Свободные генераторы документации Категория:Java Категория:Языки разметки