| Javadoc | |
|---|---|
| Тип | Генератор документации |
| Разработчик | Sun Microsystems |
| Операционная система | кроссплатформенная |
| Аппаратная платформа | Java Virtual Machine |
| Последняя версия | 1.50 |
| Лицензия | GNU GPL 2 + «Classpath exception»[1] |
| Сайт | docs.oracle.com/javase/8… |
Javadoc — генератор документации в HTML-формате из комментариев исходного кода на Java от Sun Microsystems. Javadoc — стандарт для документирования классов Java. Большинство сред разработки программного обеспечения автоматически генерируют HTML-документацию, используя Javadoc.
Javadoc также предоставляет API для создания доклетов и тэглетов, которые позволяют программисту анализировать структуру Java-приложения.
Применение
Комментарии документации применяют для:
- документирования классов,
- интерфейсов,
- полей (переменных),
- конструкторов,
- методов,
- пакетов.
В каждом случае комментарий должен находиться перед документируемым элементом.
| Список дескрипторов Javadoc | ||
|---|---|---|
| Дескриптор | Описание | Применим к |
@author | Автор | класс, интерфейс |
@version | Версия. Не более одного дескриптора на класс | класс, интерфейс |
@since | Указывает, с какой версии доступно | класс, интерфейс, поле, метод |
@see | Ссылка на другое место в документации | класс, интерфейс, поле, метод |
@param | Входной параметр метода | метод |
@return | Описание возвращаемого значения | метод |
@exception имякласса описание | Описание исключения, которое может быть послано из метода | метод |
@deprecated | Описание устаревших блоков кода | класс, интерфейс, поле, метод |
{@link reference} | Ссылка | класс, интерфейс, поле, метод |
{@value} | Описание значения переменной | статичное поле |
Для документирования переменной можно использовать следующие дескрипторы:
@see, @serial, @serialField, {@value}, @deprecated.
Для классов и интерфейсов можно использовать дескрипторы:
@see, @author, @deprecated, @param, @version.
Методы можно документировать с помощью дескрипторов:
@see, @return, @param, @deprecated, @throws, @serialData, {@inheritDoc}, @ехсерtion.
Дескрипторы {@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) {
. . .
}
См. также
Примечания
- ↑ Free and Open Source Java — FAQ (англ.). Проверено 3 февраля 2010. Архивировано 3 марта 2012 года.
- ↑ How to Write Doc Comments for the Javadoc Tool
Ссылки
Статьи
- Теория и практика Java: Мне нужно задокументировать ЭТО?
- Skipy.ru: Записки трезвого практика -> Полезное -> Создание собственных тегов javadoc
 |
Это заготовка статьи о свободном программном обеспечении. Вы можете помочь проекту, дополнив её. |
Данная страница на сайте WikiSort.ru содержит текст со страницы сайта "Википедия".
Если Вы хотите её отредактировать, то можете сделать это на странице редактирования в Википедии.
Если сделанные Вами правки не будут кем-нибудь удалены, то через несколько дней они появятся на сайте WikiSort.ru .