11

11


Строка, в которой распечатывается число, довольно интересна:
System, out. print 1 л (new DateO);
Аргумент представляет собой объект Date, который создается лишь затем, чтобы передать свое значение (автоматически преобразуемое в String) методу println(). Как только команда будет выполнена, объект Date становится ненуж¬ным, сборщик мусора заметит это, и в конце концов сам удалит его. Нам не нужно беспокоиться о его удалении самим.
Компиляция и выполнение
Чтобы скомпилировать и выполнить эту программу, а также все остальные про¬граммы в книге, вам понадобится среда разработки Java. Существует множест¬во различных сред разработок от сторонних производителей, но в этой книге мы предполагаем, что вы избрали бесплатную среду JDK Qava Developer's Kit) от фирмы Sun. Если же вы используете другие системы разработки программ , вам придется просмотреть их документацию, чтобы узнать, как компилировать и запускать программы.
Подключитесь к Интернету и посетите сайтhttp://java.sun.com. Там вы най¬дете информацию и необходимые ссылки, чтобы загрузить и установить JDK для вашей платформы.
Как только вы установите 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 описание