Javadoc

Javadoc

Тип	генератор документації
Розробник	Sun Microsystems
Стабільний випуск	1.50
Платформа	віртуальна машина Java
Ліцензія	GNU GPL 2
Вебсайт	Офіційний сайт

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.3
@exception Назва виключення Пояснення @throws Назва виключення Пояснення	Описує виключення, що може генерувати метод.	Метод	1.0 та 1.2 відповідно
{@inheritDoc}	Наслідує коментар безпосередньо від предка.	Підмінений метод	1.4
{@link Пакет. Клас#Член Опис}	Вставляє вбудоване посилання на іншу тему.	Скрізь	1.2
{@linkplain}	Вставляє вбудоване посилання на іншу тему, проте відображає його у вигляді відкритої форми шрифту.	Скрізь	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
 */
package XMLTools;

Приклад документування класу

/**
 * Клас для представлення кожного тегу в XML документів. Це контейнер з ім’ям,
 * який також може вміщувати значення, коментар, атрибути та вкладені елементи. Він
 * використовується для пакування інформації перед збереженням в 
 * <code>XMLOutputStream</code>. Також, він використовується в <code>XMLInputStream</code> 
 * для повернення прочитаної інформації.
 * 
 * @author Mir4ik
 * @version 1.0 11/06/12
 * @see XMLInputStream
 * @see XMLOutputStream
 */
public class XMLElement {
	// члени класу
}

Приклад документування методу

/**
 * Метод формує дерево XML елементів. 
 * <p>
 * <strong>Увага:</strong> Дані поза кореневим тегом XML документу буде втрачено! 
 * Використовуйте спеціальне поле для коментаря в <code>XMLElement</code>, 
 * що можна задати методом {@link XMLElement#setComment(String)}. 
 * 
 * @return 			найвищий <code>XMLElement</code> в сформованому дереві
 * @throws XMLStreamException 	якщо під час парсингу виникла виняткова ситуація
 * @throws IOException 		якщо виникла виняткова ситуація при читанні даних
 */
public XMLElement readRootTag() throws XMLStreamException, IOException {
	// код методу
}

Див. також

• JSDoc

Посилання

• Офіційний сайт Javadoc [Архівовано 6 квітня 2005 у Wayback Machine.] (англ.)
• How to Write Doc Comments for the Javadoc Tool [Архівовано 29 квітня 2020 у Wayback Machine.] (англ.)
• javadoc The Java API Documentation Generator [Архівовано 15 червня 2012 у Wayback Machine.] (англ.)

Джерела

• Schildt H. Java: The Complete Reference (7th ed.). — Osborne, 2007 (англ.) (Шилдт Г. Полный справочник по Java. — М.: Вильямс, 2007. — 1035 с.) (рос.)