русс | укр

Мови програмуванняВідео уроки php mysqlПаскальСіАсемблерJavaMatlabPhpHtmlJavaScriptCSSC#DelphiТурбо Пролог

Компьютерные сетиСистемное программное обеспечениеИнформационные технологииПрограммирование


Linux Unix Алгоритмічні мови Архітектура мікроконтролерів Введення в розробку розподілених інформаційних систем Дискретна математика Інформаційне обслуговування користувачів Інформація та моделювання в управлінні виробництвом Комп'ютерна графіка Лекції


Шановні українці! Матеріал був перекладений з російської мови. Тому можуть бути незначні помикли...

Java коментарі | Javadoc

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

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 документацію.

Переглядів: 1137

Повернутися взміст


Онлайн система числення Калькулятор онлайн звичайний Науковий калькулятор онлайн