Java коментарі

Найбільша проблема, пов'язана з документуванням коду - підтримка цієї документації. Якщо документація і код розділені, виникають труднощі, пов'язані з необхідністю внесення змін до відповідних розділів супровідної документації щоразу при зміні програмного коду. Середовище розробки пропонує рішення - зв'язати код з документацією, помістивши все в один файл.

Утиліта javadoc дозволяє вставляти HTML теги і використовувати спеціальні ярлики (дескриптори) документування. НТМ теги заголовків не використовують, щоб не порушувати стиль файлу, сформованого утилітою.

Для документування змінної можна використовувати такі дескриптори:

Для класів і інтерфейсів можна використовувати дескріпто ри:

Методи можна документувати за допомогою дескрипторів:

Після початкової комбінації символів / ** розташовується текст, який є головним описом класу, змінної або методу. Далі можна вставляти різні дескриптори. Кожен дескриптор @ повинен стояти першим в рядку. Кілька дескрипторів одного і того ж типу необхідно групувати разом. Вбудовані дескриптори (починаються з фігурної дужки) можна поміщати всередині будь-якого опису.

Утиліта javadoc в якості вхідних даних приймає файл з вихідним кодом програми. Генерує кілька НТМ файлів, що містять документацію по цій програмі. Інформація про кожному класі буде міститися в окремому НТМ файлі. Крім того, створюється дерево індексів і ієрархії. Можуть бути згенеровані і інші НТМ файли.

У середовищі Eclipse генерувати документацію можна використовуючи команду меню Project / Generate Javadoc.

Java коментарі

Дескриптори javadoc

@author опис

опцію -author, щоб включити поле в НТМ документацію.

@deprecated опис

Визначає, що клас, інтерфейс або член класу є застарілим. Рекомендується включати дескриптори @see або для того, щоб інформувати програміста про доступні альтернативні варіанти. Може використовуватися для документування змінних, методів і класів.

Визначає шлях до кореневого каталогу поточного документації.

@exception імя_ісключенія пояснення

Описує виняток для даного методу. Тут імя_ісключенія вказує повне ім'я виключення, а пояснення представляє рядок, яка описує, в яких випадках може виникнути цей виняток. Може використовуватися тільки для документування методів.

Вбудовує посилання на додаткову інформацію. При відображенні текст (якщо є) використовується в якості імені посилання.

@param імя_параметра пояснення

Документує параметр для методу або параметр-тип для класу або інтерфейсу. Може використовуватися тільки для документування методу, конструктора, узагальненого класу або інтерфейсу.

@return пояснення

Описує повертається значення методу.

@see пакет.класс # елемент текст

Забезпечує посилання на додаткову інформацію.

@serial опис

@serialData опис

Документує дані, записані за допомогою методів writeObject і writeExternal.

@serialField ім'я тип опис

@since випуск

Показує, що клас або елемент класу був вперше представлені в певному випуску. Тут випуску представлено рядок, в якій вказано випуск або версія, починаючи з якого ця особливість стала доступною.

@throws імя_ісключенія пояснення

Має той же призначення, що і дескриптор @exception.

Відображає значення наступної за ним константи, якій має бути поле static.

Відображає значення певного поля static.

@version інформація

Надає інформацію про версії (як правило, номер). При виконанні утиліти javadoc потрібно вказати опцію -version, щоб цей дескриптор включити в НТМ документацію.

Схожі статті