Топ питань
Часова шкала
Чат
Перспективи
Javadoc
З Вікіпедії, вільної енциклопедії
Remove ads
Javadoc — генератор документації в HTML-форматі з коментарів вихідного коду на Java від Sun Microsystems. Цей формат був обраний для забезпечення можливості зв'язати воєдино пов'язані документи за допомогою посилань. Коментарі javadoc стали «де факто» стандартом для документування створених Java-класів. Більшість середовищ розробки, таких як Eclipse та Netbeans автоматично генерують документацію за допомогою javadoc.
Javadoc також забезпечує інтерфейс для створення доклетів та теглетів, що надають можливість аналізувати структуру Java-програми.
Remove ads
Використання
В мові програмування Java існує три типи коментарів, лише один з яких може бути використаний для створення javadoc — це так званий коментар документації. В коді він виділяється такою конструкцією:
/**
* Так можна коментувати змінні класу.
*/
Ці коментарі дають можливість додавати в програму інформацію про неї, яка пізніше може бути використана утилітою javadoc (входить до складу Java Development Kit) для створення HTML-файлів. Коментарі документації можна використовувати при коментуванні:
- полів (змінних);
- методів;
- конструкторів:
- класів;
- інтерфейсів;
- пакетів.
Варто відмітити, що в будь-якому разі коментарі повинні знаходитися перед документованим об'єктом.
В коментарях також можна використовувати і стандартні HTML теги, наприклад <strong>
. Проте на використання деяких з них накладається заборона, наприклад заголовки порушують зовнішній вигляд HTML-файлу, сформованого за допомогою утиліти javadoc.
Remove ads
Дескриптори
Узагальнити
Перспектива
В документації можна також використовувати спеціальні дескриптори, призначені для вказування утиліті javadoc певної інформації. Їх поділяють на:
- автономні (починаються з символу @, наприклад
@see
); - вбудовані (починаються з символу {, наприклад
{@code}
).
Відмінність цих дескрипторів полягає у тому, що автономні мають використовуватись у власному рядку, в той час як вбудовані можуть бути використані всередині великого опису. Приклади дескрипторів наведені в таблиці.
Remove ads
Приклади документування
Узагальнити
Перспектива
Приклад документування пакету
Описаний код має бути розміщений у файлі 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 [Архівовано 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 с.) (рос.)
Wikiwand - on
Seamless Wikipedia browsing. On steroids.
Remove ads