20

20


/* Это комментарий,

* распространяющийся на

* несколько строк */

Впрочем, все символы между /* и */ игнорируются, и с таким же успехом можно использовать запись

/* Это комментарий, распространяющийся на несколько строк */

Второй вид комментария пришел из языка С++. Однострочный коммента¬рий начинается с комбинации // и продолжается до конца строки. Такой стиль очень удобен и прост, поэтому широко используется на практике. Вам не при¬ходится искать на клавиатуре сначала символ /, а затем * (вместо этого вы два¬жды нажимаете одну и ту же клавишу), и не нужно закрывать комментарий. Поэтому часто можно увидеть такие примеры:

// это комментарий в одну строку

Документация в комментариях

Пожалуй, основные проблемы с документированием кода связаны с его сопро¬вождением. Если код и его документация существуют раздельно, корректиро¬вать описание программы при каждом ее изменении становится задачей не из лег¬ких. Решение выглядит очень просто: совместить код и документацию. Проще всего объединить их в одном файле. Но для полноты картины понадобится спе¬циальный синтаксис комментариев, чтобы помечать документацию, и инстру¬мент, который извлекал бы эти комментарии и оформлял их в подходящем виде. Именно это было сделано в Java.

Инструмент для извлечения комментариев называется javadoc, он является частью пакета JDK. Некоторые возможности компилятора Java используются в нем для поиска пометок в комментариях, включенных в ваши программы. Он не только извлекает помеченную информацию, но также узнает имя класса или метода, к которому относится данный фрагмент документации. Таким образом, с минимумом затраченных усилий можно создать вполне приличную сопрово¬дительную документацию для вашей программы.

Результатом работы программы javadoc является HTML-файл, который можно просмотреть в браузере. Таким образом, утилита javadoc позволяет соз¬давать и поддерживать единый файл с исходным текстом и автоматически строить полезную документацию. В результае получается простой и практич¬ный стандарт по созданию документации, поэтому мы можем ожидать (и даже требовать) наличия документации для всех библиотек Java.

Вдобавок, вы можете дополнить javadoc своими собственными расширениями, называемыми доклетами (doclets), в которых можно проводить специальные операции над обрабатываемыми данными (например, выводить их в другом формате).

Далее следует лишь краткое введение и обзор основных возможностей java¬doc. Более подробное описание можно найти в документации JDK. Распаковав документацию, загляните в папку tooldocs (или перейдите по ссылке tooldocs).

Синтаксис

Все команды javadoc находятся только внутри комментариев /**. Комментарии, как обычно, завершаются последовательностью */. Существует два основных способа работы с javadoc: встраивание HTML-текста или использование размет¬ки документации (тегов). Самостоятельные теги документации — это команды, которые начинаются символом @ и размещаются с новой строки комментария.

(Начальный символ * игнорируется.) Встроенные теги документации могут располагаться в любом месте комментария javadoc, также начинаются со знака @, но должны заключаться в фигурные скобки.

Существует три вида документации в комментариях для разных элементов кода: класса, переменной и метода. Комментарий к классу записывается прямо перед его определением; комментарий к переменной размещается непосредст¬венно перед ее определением, а комментарий к методу тоже записывается пря¬мо перед его определением. Простой пример:

//. object/Documentationl.java /** Комментарий к классу */ public class Documentationl {

/** Комментарий к переменной */ public int i:

/** Комментарий к методу */ public void f() {} } ///-

Заметьте, что javadoc обрабатывает документацию в комментариях только для членов класса с уровнем доступа public и protected. Комментарии для чле¬нов private и членов с доступом в пределах пакета игнорируются, и документа¬ция по ним не строится. (Впрочем, флаг -private включает обработку и этих членов). Это вполне логично, поскольку только public- и protected-члены дос¬тупны вне файла, и именно они интересуют программиста-клиента.

Результатом работы программы является HTML-файл в том же формате, что и остальная документация для Java, так что пользователям будет привычно и удобно просматривать и вашу документацию. Попробуйте набрать текст пре¬дыдущего примера, «пропустите» его через javadoc и просмотрите полученный HTML-файл, чтобы увидеть результат.

Встроенный HTML

Javadoc вставляет команды HTML в итоговый документ. Это позволяет полно¬стью использовать все возможности HTML; впрочем, данная возможность пре¬жде всего ориентирована на форматирование кода:

II: object/Documentation2.java

* <pre>

* System out print!n(new DateO);

* </pre>

III:-

Вы можете использовать HTML точно так же, как в обычных страницах, чтобы привести описание к нужному формату:

II: object/Documentation3.java /**

* Можно <ет>даже</ет> вставить список:

* <ol>

* <li> Пункт первый

* <li> Пункт второй

* <li> Пункт третий

* </ol>

///:-

Javadoc игнорирует звездочки в начале строк, а также начальные пробелы. Текст переформатируется таким образом, чтобы он отвечал виду стандартной документации. Не используйте заголовки вида <hl> или <h2> во встроенном HTML, потому что javadoc вставляет свои собственные заголовки и ваши могут с ними «пересечься».

Встроенный HTML-код поддерживается всеми типами документации в комментариях — для классов, переменных или методов.

Примеры тегов

Далее описаны некоторые из тегов javadoc, используемых при документирова¬нии программы. Прежде чем применять javadoc для каких-либо серьезных це¬лей, просмотрите руководство по нему в документации пакета JDK, чтобы по¬лучить полную информацию о его использовании.

@see: ссылка на другие классы

Тег позволяет ссылаться на документацию к другим классам. Там, где были за¬писаны теги @see, Javadoc создает HTML-ссылки на другие документы. Основ¬ные формы использования тега:

@see имя класса

@see полное-имя-класса

@see полное-имя-класса#имя-метода

Каждая из этих форм включает в генерируемую документацию замечание See Also («см. также») со ссылкой на указанные классы. Javadoc не проверяет пе¬редаваемые ему гиперссылки.