Javadoc — генератор документації в HTML-форматі з коментарів вихідного коду на Java від Sun Microsystems. Цей формат був обраний для забезпечення можливості зв'язати воєдино пов'язані документи за допомогою посилань. Коментарі javadoc стали «де факто» стандартом для документування створених Java-класів. Більшість середовищ розробки, таких як Eclipse та Netbeans автоматично генерують документацію за допомогою javadoc.
Javadoc також забезпечує інтерфейс для створення доклетів та теглетів, що надають можливість аналізувати структуру Java-програми.
Використання
В мові програмування Java існує три типи коментарів, лише один з яких може бути використаний для створення javadoc — це так званий коментар документації. В коді він виділяється такою конструкцією:
/** * Так можна коментувати змінні класу. */
Ці коментарі дають можливість додавати в програму інформацію про неї, яка пізніше може бути використана утилітою javadoc (входить до складу Java Development Kit) для створення HTML-файлів. Коментарі документації можна використовувати при коментуванні:
Варто відмітити, що в будь-якому разі коментарі повинні знаходитися перед документованим об'єктом.
В коментарях також можна використовувати і стандартні HTML теги, наприклад <strong>. Проте на використання деяких з них накладається заборона, наприклад заголовки порушують зовнішній вигляд HTML-файлу, сформованого за допомогою утиліти javadoc.
Дескриптори
В документації можна також використовувати спеціальні дескриптори, призначені для вказування утиліті javadoc певної інформації. Їх поділяють на:
автономні (починаються з символу @, наприклад @see);
вбудовані (починаються з символу {, наприклад {@code}).
Відмінність цих дескрипторів полягає у тому, що автономні мають використовуватись у власному рядку, в той час як вбудовані можуть бути використані всередині великого опису.
Приклади дескрипторів наведені в таблиці.
Дескриптор Параметр
Призначення
Використання
З версії
@authorОпис
Ідентифікує автора.
Клас, інтерфейс
1.0
{@codeФрагмент коду}
Відображає інформацію «як є», без обробки HTML-стилю, проте з використанням шрифту коду.
Скрізь
1.5
@deprecatedОпис
Описує застарілий клас або його член. При використанні бажано вказувати, чим було замінено функціональність.
Клас, інтерфейс, метод, змінна
1.0
{@docRoot}
Визначає шлях до корінного каталогу поточної директорії.
Вставляє вбудоване посилання на іншу тему, проте відображає його у вигляді відкритої форми шрифту.
Скрізь
1.4
{@literalОпис}
Відображає інформацію «як є», без обробки HTML-стилю.
Скрізь
1.5
@paramНазва параметру Опис
Документує параметр методу, класу чи інтерфейсу. При використанні не потрібно вказувати тип параметру.
Клас, інтерфейс, метод
1.0
@returnОпис
Описує значення, що повертає метод.
Метод
1.0
@seeТема @see Пакет. Клас#Член Опис
Визначає посилання на іншу тему документації.
Клас, інтерфейс, метод, змінна
1.0
@serialОпис
Документує змінну, що серіалізується за замовчуванням.
Змінна
1.2
@serialDataОпис
Документує дані, записані методами writeObject() та writeExternal().
Метод
1.2
@serialFieldОпис
Документує компонент ObjectStreamField.
Змінна
1.2
@sinceВерсія
Показує, коли було введено дану функціональність.
Скрізь
1.1
{@value} {@valueПакет. Клас#Змінна}
Повертає значення статичної змінної.
Статична змінна
1.4
@versionВерсія
Визначає версію класу і може використовуватися в ньому лише раз.
Клас, інтерфейс
1.0
Приклади документування
Приклад документування пакету
Описаний код має бути розміщений у файлі package-info.java, що, в свою чергу, має розміщуватися в документованому пакеті.
/** * Пакет включає класи для використання XML потоків в програмах. * * @author Mir4ik * @version 1.0 10/06/12 */packageXMLTools;
Приклад документування класу
/** * Клас для представлення кожного тегу в XML документів. Це контейнер з ім’ям, * який також може вміщувати значення, коментар, атрибути та вкладені елементи. Він * використовується для пакування інформації перед збереженням в * <code>XMLOutputStream</code>. Також, він використовується в <code>XMLInputStream</code> * для повернення прочитаної інформації. * * @author Mir4ik * @version 1.0 11/06/12 * @see XMLInputStream * @see XMLOutputStream */publicclassXMLElement{// члени класу}
Приклад документування методу
/** * Метод формує дерево XML елементів. * <p> * <strong>Увага:</strong> Дані поза кореневим тегом XML документу буде втрачено! * Використовуйте спеціальне поле для коментаря в <code>XMLElement</code>, * що можна задати методом {@link XMLElement#setComment(String)}. * * @return найвищий <code>XMLElement</code> в сформованому дереві * @throws XMLStreamException якщо під час парсингу виникла виняткова ситуація * @throws IOException якщо виникла виняткова ситуація при читанні даних */publicXMLElementreadRootTag()throwsXMLStreamException,IOException{// код методу}
