Брюс Эккель - Философия Java3
java HelloDate
и вы увидите сообщение1 и число как результат работы программы.
Эта последовательность действий позволяет откомпилировать и выполнить любую программу-пример из этой книги. Однако также вы увидите, что каждая папка содержит файл build.xml с командами для инструмента ant по автоматической сборке файлов для данной главы. После установки ant с сайта http://jakarta. apache.org/ant можно будет просто набрать команду ant в командной строке, чтобы скомпилировать и запустить программу из любого примера. Если ant на вашем компьютере еще не установлен, команды javac и java придется вводить вручную.
Комментарии и встроенная документация
В Java приняты два вида комментариев. Первый — традиционные комментарии в стиле С, также унаследованные языком С++. Такие комментарии начинаются с комбинации /* и распространяются иногда на множество строк, после чего заканчиваются символами */. Заметьте, что многие программисты начинают каждую новую строку таких комментариев символом *, соответственно, часто можно увидеть следующее:
/* Это комментарий,
* распространяющийся на
* несколько строк */
Впрочем, все символы между /* и */ игнорируются, и с таким же успехом можно использовать запись
/* Это комментарий, распространяющийся на несколько строк */
Второй вид комментария пришел из языка С++. Однострочный комментарий начинается с комбинации // и продолжается до конца строки. Такой стиль очень удобен и прост, поэтому широко используется на практике. Вам не приходится искать на клавиатуре сначала символ /, а затем * (вместо этого вы дважды нажимаете одну и ту же клавишу), и не нужно закрывать комментарий. Поэтому часто можно увидеть такие примеры:
// это комментарий в одну строку
Документация в комментариях
Пожалуй, основные проблемы с документированием кода связаны с его сопровождением. Если код и его документация существуют раздельно, корректировать описание программы при каждом ее изменении становится задачей не из легких. Решение выглядит очень просто: совместить код и документацию. Проще всего объединить их в одном файле. Но для полноты картины понадобится специальный синтаксис комментариев, чтобы помечать документацию, и инструмент, который извлекал бы эти комментарии и оформлял их в подходящем виде. Именно это было сделано в Java.
Инструмент для извлечения комментариев называется javadoc, он является частью пакета JDK. Некоторые возможности компилятора Java используются в нем для поиска пометок в комментариях, включенных в ваши программы. Он не только извлекает помеченную информацию, но также узнает имя класса или метода, к которому относится данный фрагмент документации. Таким образом, с минимумом затраченных усилий можно создать вполне приличную сопроводительную документацию для вашей программы.
Результатом работы программы javadoc является HTML-файл, который можно просмотреть в браузере. Таким образом, утилита javadoc позволяет создавать и поддерживать единый файл с исходным текстом и автоматически строить полезную документацию. В результае получается простой и практичный стандарт по созданию документации, поэтому мы можем ожидать (и даже требовать) наличия документации для всех библиотек Java.
Вдобавок, вы можете дополнить javadoc своими собственными расширениями, называемыми доклетами (doclets), в которых можно проводить специальные операции над обрабатываемыми данными (например, выводить их в другом формате).
Далее следует лишь краткое введение и обзор основных возможностей javadoc. Более подробное описание можно найти в документации 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 не проверяет передаваемые ему гиперссылки.
{@link пакет.класс#член_класса метка}
Тег очень похож на @see, не считая того, что он может использоваться как встроенный, а вместо стандартного текста See Also в ссылке размещается текст, указанный в поле метка.
{@docRoot}
Позволяет получить относительный путь к корневой папке, в которой находится документация. Полезен при явном задании ссылок на страницы из дерева документации.
{@inheritDoc}
Наследует документацию базового класса, ближайшего к документируемому классу, в текущий файл с документацией.
@version
Имеет следующую форму:
(Pversion информация-о-версии
Поле информации о версии содержит ту информацию, которую вы сочли нужным включить. Когда в командной строке javadoc указывается опция -version, в созданной документации специально отводится место, заполняемое информацией о версиях.
@author
Записывается в виде
©author информация-об-авторе
Предполагается, что поле информация-об-авторе представляет собой имя автора, хотя в него также можно включить адрес электронной почты и любую другую информацию. Когда в командной строке javadoc указывается опция -author, в созданной документации сохраняется информация об авторе.
Для создания списка авторов можно записать сразу несколько таких тегов, но они должны размещаться последовательно. Вся информация об авторах объединяется в один раздел в сгенерированном коде HTML.
@since
Тег позволяет задать версию кода, с которой началось использование некоторой возможности. В частности, он присутствует в HTML-документации по Java, где служит для указания версии JDK.
@param
Полезен при документировании методов. Форма использования:
