Javadoc
| Розробник(и) | Sun Microsystems |
|---|---|
| Стабільний випуск | 1.50 |
| Тип | генератор документації |
| Ліцензія | GNU GPL 2 |
| Сайт | Офіційний сайт |
Javadoc — генератор документації в HTML-форматі з коментарів вихідного коду на Java від Sun Microsystems. Цей формат був обраний для забезпечення можливості зв’язати воєдино пов’язані документи за допомогою посилань. Коментарі javadoc стали “де факто” стандартом для документування створених Java-класів. Більшість середовищ розробки, таких як Eclipse та Netbeans автоматично генерують документацію за допомогою javadoc.
Javadoc також забезпечує API для створення доклетів та теглетів, що надають можливість аналізувати структуру 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 { // код методу }
Див. також [ред.]
Посилання [ред.]
- Офіційний сайт Javadoc (англ.)
- How to Write Doc Comments for the Javadoc Tool (англ.)
- javadoc The Java API Documentation Generator Шаблон:Ref-eng
Джерела [ред.]
- Schildt H. Java: The Complete Reference (7th ed.). — Osborne, 2007 (англ.) (Шилдт Г. Полный справочник по Java. — М.: Вильямс, 2007. — 1035 с.) (рос.)
