Найбільша проблема, пов'язана з документуванням коду - підтримка цієї документації. Якщо документація і код розділені, виникають труднощі, пов'язані з необхідністю внесення змін у відповідні розділи супровідної документації кожного разу при зміні програмного коду. Середовище розробки пропонує рішення - зв'язати код з документацією, помістивши всі в один файл.
Java коментарі необхідні для коментування програми і для складання або оформлення документації. Існує спеціальний синтаксис для оформлення документації у вигляді коментарів і інструмент для виділення цих коментарів в зручну форму. Інструмент називається javadoc. Обробляючи файл з вихідним текстом програми, він виділяє позначену документацію з коментарів і пов'язує з іменами відповідних класів або методів. Таким чином, витративши мінімум зусиль на оформлення коментарів, можна отримати гарну документацію до програми.
На виході javadoc виходить HTML файл, який можна переглянути будь-яким веб-оглядачем. Цей інструмент дозволяє створювати і підтримувати файли з вихідним текстом і, при необхідності, генерувати супровідну документацію. Бібліотеки Java зазвичай документуються саме таким способом, саме тому при розробці програм зручно використовувати JDK з комментированным для javadoc вихідним текстом бібліотек замість JRE, де файли відсутні.
Java має три типи коментарів. Перші два типи: //... і /*...*/. Третій тип називається коментарем документації. Такий коментар починається з послідовності символів /** і закінчується послідовністю */. Коментарі документації дозволяють додавати в програму інформацію про неї самої. За допомогою утиліти javadoc (що входить до складу JDK) цю інформацію можна отримувати і відправляти в НТМL файл.
Утиліта javadoc дозволяє вставляти HTML теги і використовувати спеціальні ярлики (теги) документування. НТМL теги заголовків не використовують, щоб не порушувати стильфайла, сформованого утилітою.
Теги javadoc, що починаються з символу @, називаються автономними і повинні міститися з початку рядка коментарю (лідируючий символ * ігнорується). Дескриптори, що починаються з фігурною дужки, наприклад {@code}, називаються вбудованими і можуть застосовуватися всередині описания.
Коментарі документації застосовують для документування класів, інтерфейсів, полів (змінних), конструкторів і методів. У кожному разі коментар повинен перебувати перед документируемым елементом.
Для документування змінної можна використовувати наступні теги:
@see, @serial, @serialField, value} {@, @deprecated.
Для класів і інтерфейсів можна використовувати теги:
@see, @author, @deprecated, @param, @version.
Методи можна документувати з допомогою дескрипторів:
@see, @return, @param, @deprecated, @throws, @serialData, {@inheritDoc}, @ехсерtiоn.
Теги {@link}, {@docRoot}, {@code}, {@}, @since, {@linkplain} можуть застосовуватися де завгодно.
Загальна форма коментарів
Після початкової комбінації символів /** розташовується текст, який є головним описом класу, змінної або методу. Далі можна вставляти різні дескриптори. Кожен дескриптор @ повинен стояти першим в рядку. Кілька дескрипторів одного і того ж типу необхідно групувати разом. Вбудовані дескриптори (починаються з фігурною дужки) можна поміщати всередині будь-якого описания.
Утиліта javadoc в якості вхідних даних приймає файл з вихідним кодом програми. Генерує кілька НТМL файлів, що містять документацію по цій програмі. Інформація про кожному класі буде міститися в окремому НТМL файлі. Крім того, створюється дерево індексів і ієрархії. Можуть бути згенерували і інші НТМL файли.
У середовищі Eclipse генерувати документацію можна використовуючи команду меню Project/Generate Javadoc...
Теги javadoc
@author опис
Документує автора класу. При виклику утиліти javadoc потрібно задати
опцію-author, щоб включити поле в НТМL документацію.
{@code фрагмент_кода}
пробить можливим вбудовувати в коментар текст (фрагмент коду). Цей текст буде відображатися з допомогою шрифту коду без подальшої обробки в НТМL.
@deprecated опис
Визначає, що клас, інтерфейс або член класу є застарілим. Рекомендується включати дескриптори @see або {@link} для того, щоб інформувати програміста про доступні альтернативні варіанти. Може використовуватися для документування змінних, методів і класів.
{@docRoot}
Визначає шлях до кореня поточної документації.
@exception имя_исключения пояснення
Описує виняток для даного методу. Тут имя_исключения вказує повне ім'я виключення, а пояснення представляє рядок, що описує, в яких випадках може виникнути цей виняток. Може використовуватися тільки для документування методів.
{@inheritDoc}
Успадковує коментар від безпосереднього суперкласу.
{@link пакет.класс#елемент текст}
Вбудовує посилання на додаткову інформацію. При відображенні текст (якщо є) використовується в якості імені посилання.
{@linkplain пакет.класс#елемент текст}
Вбудовує посилання. Посилання відображається шрифтом основного тексту.
{@ опис}
Дозволяє вбудовувати текст у коментар. Цей текст відображається "як Є" без подальшої обробки HTML.
@param имя_параметра пояснення
Документує параметр для методу або параметр-тип для класу або інтерфейсу. Може використовуватися тільки для документування методу, конструктора, узагальненого класу або інтерфейсу.
@return пояснення
Описує повертає значення методу.
@see посилання
@see пакет.класс#елемент текст
Забезпечує посилання на додаткову інформацію.
@serial опис
Визначає коментар для поля, сериализируемого за замовчуванням.
@serialData опис
Документує дані, записані за допомогою методів writeObject і writeExternal.
@serialField ім'я тип опис
Для класу, що реалізує Serializable, дескриптор забезпечує коментарі для компонента ObjectStreamField. Тут ім'я представляє ім'я поля, тип представляє його тип, а опис - коментар для даного поля.
@since випуск
Показує, що клас або елемент класу був вперше представлені в певному випуску. Тут випуск є рядок, в якому вказано випуск або версія, починаючи з якого ця особливість стала доступною.
@throws имя_исключения пояснення
Має те ж призначення, що і дескриптор @exception.
{@value}
Відображає значення наступного за ним константи, якою має бути поле static.
{@value пакет.класс#полі}
Відображає значення певного поля static.
@version інформація
Представляє інформацію про версії (як правило, номер). При виконанні утиліти javadoc потрібно вказати параметр-version, щоб цей дескриптор включити в НТМL документацію.
