9
Как только вы установите JDK и правильно установите пути запуска, в ре¬зультате чего система сможет найти утилиты javac и java, загрузите и распакуй¬те исходные тексты программ для этой книги (их можно загрузить с сайтаwww.MindView.net). Там вы обнаружите каталоги (папки) для каждой главы книги. Перейдите в папку objects и выполните команду
javac HelloDate java
Команда не должна выводить каких-либо сообщений. Если вы получили со¬общение об ошибке, значит, вы неверно установили JDK и вам нужно разо¬браться со своими проблемами.
И наоборот, если все прошло успешно, выполните следующую команду:
java HelloDate
и вы увидите сообщение и число как результат работы программы.
Эта последовательность действий позволяет откомпилировать и выполнить любую программу-пример из этой книги. Однако также вы увидите, что каждая папка содержит файл build.xml с командами для инструмента ant по автоматиче¬ской сборке файлов для данной главы. После установки ant с сайтаhttp://jakarta. apache.org/ant можно будет просто набрать команду ant в командной строке, чтобы скомпилировать и запустить программу из любого примера. Если ant на вашем компьютере еще не установлен, команды javac и java придется вводить вручную.
Комментарии и встроенная документация
В Java приняты два вида комментариев. Первый — традиционные комментарии в стиле С, также унаследованные языком С++. Такие комментарии начинаются с комбинации /* и распространяются иногда на множество строк, после чего за¬канчиваются символами */. Заметьте, что многие программисты начинают каж¬дую новую строку таких комментариев символом *, соответственно, часто мож¬но увидеть следующее:
/* Это комментарий,
* распространяющийся на
* несколько строк */
Впрочем, все символы между /* и */ игнорируются, и с таким же успехом можно использовать запись
/* Это комментарий, распространяющийся на несколько строк */
Второй вид комментария пришел из языка С++. Однострочный коммента¬рий начинается с комбинации // и продолжается до конца строки. Такой стиль очень удобен и прост, поэтому широко используется на практике. Вам не при¬ходится искать на клавиатуре сначала символ /, а затем * (вместо этого вы два¬жды нажимаете одну и ту же клавишу), и не нужно закрывать комментарий. Поэтому часто можно увидеть такие примеры:
// это комментарий в одну строку
Документация в комментариях
Пожалуй, основные проблемы с документированием кода связаны с его сопро¬вождением. Если код и его документация существуют раздельно, корректиро¬вать описание программы при каждом ее изменении становится задачей не из лег¬ких. Решение выглядит очень просто: совместить код и документацию. Проще всего объединить их в одном файле. Но для полноты картины понадобится спе¬циальный синтаксис комментариев, чтобы помечать документацию, и инстру¬мент, который извлекал бы эти комментарии и оформлял их в подходящем виде. Именно это было сделано в 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 не проверяет пе¬редаваемые ему гиперссылки.{@linkпакет.класс#член_класса метка}
Тег очень похож на @see, не считая того, что он может использоваться как встроенный, а вместо стандартного текста See Also в ссылке размещается текст, указанный в поле метка.{@docRoot}
Позволяет получить относительный путь к корневой папке, в которой находит¬ся документация. Полезен при явном задании ссылок на страницы из дерева документации.{@inheritDoc}
Наследует документацию базового класса, ближайшего к документируемому классу, в текущий файл с документацией.
@version
Имеет следующую форму:
(Pversion информация-о-версии
Поле информации о версии содержит ту информацию, которую вы сочли нуж¬ным включить. Когда в командной строке javadoc указывается опция -version, в созданной документации специально отводится место, заполняемое информа¬цией о версиях.
@author
Записывается в виде
©author информация-об-авторе
Предполагается, что поле информация-об-авторе представляет собой имя ав¬тора, хотя в него также можно включить адрес электронной почты и любую другую информацию. Когда в командной строке javadoc указывается опция -author, в созданной документации сохраняется информация об авторе.
Для создания списка авторов можно записать сразу несколько таких тегов, но они должны размещаться последовательно. Вся информация об авторах объ¬единяется в один раздел в сгенерированном коде HTML.
@since
Тег позволяет задать версию кода, с которой началось использование некото¬рой возможности. В частности, он присутствует в HTML-документации по Java, где служит для указания версии JDK.
@param
Полезен при документировании методов. Форма использования:
@param имя-параметра описание
где имя-параметра — это идентификатор в списке параметров метода, а описа¬ние — текст описания, который можно продолжить на несколько строк. Описа¬ние считается завершенным, когда встретится новый тег. Можно записывать любое количество тегов @param, по одному для каждого параметра метода.
©return
Форма использования:
©return описание
где описание объясняет, что именно возвращает метод. Описание может состо¬ять из нескольких строк.
@throws
Исключения будут рассматриваться в главе 9. В двух словах это объекты, кото¬рые можно «возбудить» (throw) в методе, если его выполнение потерпит неудачу. Хотя при вызове метода создается всегда один объект исключения, определен¬ный метод может вырабатывать произвольное количество исключений, и все они требуют описания. Соответственно, форма тега исключения такова:
©throws полное-имя-класса описание
где полное-имя-класса дает уникальное имя класса исключения, который где-то определен, а описание (расположенное на произвольном количестве строк) объясняет, почему данный метод способен создавать это исключение при своем вызове.
@deprecated
Тег используется для пометки устаревших возможностей, замещенных новыми и улучшенными. Он сообщает о том, что определенные средства программы не следует использовать, так как в будущем они, скорее всего, будут убраны. В Java SE5 тег @deprecated был заменен директивой @Deprecated (см. далее).
Пример документации
Вернемся к нашей первой программе на Java, но на этот раз добавим в нее ком¬ментарии со встроенной документацией:
//: object/Hel1oDate.java import java util.*;
/** Первая программа-пример книги.
* Выводит строку и текущее число.
* ^author Брюс Эккель
* ^authorwww.MindViewnet
* (Aversion 4.0 */
public class HelloDate {
/** Точка входа в класс и приложение
* @param args Массив строковых аргументов
* @throws exceptions Исключения не выдаются */
public static void main(String[] args) {
System out.printlnCTIpMBeT. сегодня: "); System.out.println(new DateO);
}
} /* Output. (55* match) Привет, сегодня. Wed Oct 05 14:39:36 MDT 2005 */// ~
В первой строке файла использована моя личная методика помещения спе¬циального маркера //: в комментарий как признака того, что в этой строке ком¬ментария содержится имя файла с исходным текстом. Здесь указывается путь к файлу (object означает эту главу) с последующим именем файла . Последняя строка также завершается комментарием (///:~), обозначающим конец исход¬ного текста программы. Он помогает автоматически извлекать из текста книги программы для проверки компилятором и выполнения.
Тег /* Output: обозначает начало выходных данных, сгенерированных дан¬ным файлом. В этой форме их можно автоматически проверить на точность.