Найбільша проблема, пов'язана з документуванням коду - підтримка цієї документації. Якщо документація і код розділені, виникають труднощі, пов'язані з необхідністю внесення змін до відповідних розділів супровідної документації щоразу при зміні програмного коду. Середовище розробки пропонує рішення - зв'язати код з документацією, помістивши все в один файл.
Утиліта javadoc дозволяє вставляти HTML теги і використовувати спеціальні ярлики (дескриптори) документування. НТМ теги заголовків не використовують, щоб не порушувати стиль файлу, сформованого утилітою.
Для документування змінної можна використовувати такі дескриптори:
Для класів і інтерфейсів можна використовувати дескріпто ри:
Методи можна документувати за допомогою дескрипторів:
Після початкової комбінації символів / ** розташовується текст, який є головним описом класу, змінної або методу. Далі можна вставляти різні дескриптори. Кожен дескриптор @ повинен стояти першим в рядку. Кілька дескрипторів одного і того ж типу необхідно групувати разом. Вбудовані дескриптори (починаються з фігурної дужки) можна поміщати всередині будь-якого опису.
Утиліта javadoc в якості вхідних даних приймає файл з вихідним кодом програми. Генерує кілька НТМ файлів, що містять документацію по цій програмі. Інформація про кожному класі буде міститися в окремому НТМ файлі. Крім того, створюється дерево індексів і ієрархії. Можуть бути згенеровані і інші НТМ файли.
У середовищі Eclipse генерувати документацію можна використовуючи команду меню Project / Generate Javadoc.
Дескриптори javadoc
@author опис
опцію -author, щоб включити поле в НТМ документацію.
@deprecated опис
Визначає, що клас, інтерфейс або член класу є застарілим. Рекомендується включати дескриптори @see або для того, щоб інформувати програміста про доступні альтернативні варіанти. Може використовуватися для документування змінних, методів і класів.
Визначає шлях до кореневого каталогу поточного документації.
@exception імя_ісключенія пояснення
Описує виняток для даного методу. Тут імя_ісключенія вказує повне ім'я виключення, а пояснення представляє рядок, яка описує, в яких випадках може виникнути цей виняток. Може використовуватися тільки для документування методів.
Вбудовує посилання на додаткову інформацію. При відображенні текст (якщо є) використовується в якості імені посилання.
@param імя_параметра пояснення
Документує параметр для методу або параметр-тип для класу або інтерфейсу. Може використовуватися тільки для документування методу, конструктора, узагальненого класу або інтерфейсу.
@return пояснення
Описує повертається значення методу.
@see пакет.класс # елемент текст
Забезпечує посилання на додаткову інформацію.
@serial опис
@serialData опис
Документує дані, записані за допомогою методів writeObject і writeExternal.
@serialField ім'я тип опис
@since випуск
Показує, що клас або елемент класу був вперше представлені в певному випуску. Тут випуску представлено рядок, в якій вказано випуск або версія, починаючи з якого ця особливість стала доступною.
@throws імя_ісключенія пояснення
Має той же призначення, що і дескриптор @exception.
Відображає значення наступної за ним константи, якій має бути поле static.
Відображає значення певного поля static.
@version інформація
Надає інформацію про версії (як правило, номер). При виконанні утиліти javadoc потрібно вказати опцію -version, щоб цей дескриптор включити в НТМ документацію.