- Javadoc
-
Javadoc Тип Разработчик Sun Microsystems
Операционная система кроссплатформенная
Последняя версия 1.50
Лицензия Сайт 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) { . . . }
См. также
Примечания
- ↑ Free and Open Source Java — FAQ (англ.). Архивировано из первоисточника 3 марта 2012. Проверено 3 февраля 2010.
- ↑ How to Write Doc Comments for the Javadoc Tool
Ссылки
Статьи
- Теория и практика Java: Мне нужно задокументировать ЭТО?
- Skipy.ru: Записки трезвого практика -> Полезное -> Создание собственных тегов javadoc
Категории:- Программное обеспечение по алфавиту
- Свободные генераторы документации
- Java
- Языки разметки
Wikimedia Foundation. 2010.