Философия Java3
Шрифт:
Результатом работы программы является HTML-файл в том же формате, что и остальная документация для Java, так что пользователям будет привычно и удобно просматривать и вашу документацию. Попробуйте набрать текст предыдущего примера, «пропустите» его через javadoc и просмотрите полученный HTML-файл, чтобы увидеть результат.
Встроенный HTML
Javadoc вставляет команды HTML в итоговый документ. Это позволяет полностью использовать все возможности HTML; впрочем, данная возможность прежде всего ориентирована на форматирование кода:
II: object/Documentation2.java
* <pre>
* System out print!n(new DateO);
* </pre>
III:-
Вы
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
Записывается в виде
Предполагается, что поле информация-об-авторе представляет собой имя автора, хотя в него также можно включить адрес электронной почты и любую другую информацию. Когда в командной строке javadoc указывается опция -author, в созданной документации сохраняется информация об авторе.
Для
создания списка авторов можно записать сразу несколько таких тегов, но они должны размещаться последовательно. Вся информация об авторах объединяется в один раздел в сгенерированном коде HTML.@since
Тег позволяет задать версию кода, с которой началось использование некоторой возможности. В частности, он присутствует в HTML-документации по Java, где служит для указания версии JDK.
@param
Полезен при документировании методов. Форма использования:
@param имя-параметра описание
где имя-параметра — это идентификатор в списке параметров метода, а описание — текст описания, который можно продолжить на несколько строк. Описание считается завершенным, когда встретится новый тег. Можно записывать любое количество тегов @param, по одному для каждого параметра метода.
Форма использования:
где описание объясняет, что именно возвращает метод. Описание может состоять из нескольких строк.
@throws
Исключения будут рассматриваться в главе 9. В двух словах это объекты, которые можно «возбудить» (throw) в методе, если его выполнение потерпит неудачу. Хотя при вызове метода создается всегда один объект исключения, определенный метод может вырабатывать произвольное количество исключений, и все они требуют описания. Соответственно, форма тега исключения такова:
где полное-имя-класса дает уникальное имя класса исключения, который где-то определен, а описание (расположенное на произвольном количестве строк) объясняет, почему данный метод способен создавать это исключение при своем вызове.
@deprecated
Тег используется для пометки устаревших возможностей, замещенных новыми и улучшенными. Он сообщает о том, что определенные средства программы не следует использовать, так как в будущем они, скорее всего, будут убраны. В Java SE5 тег @deprecated был заменен директивой @Deprecated (см. далее).
Пример документации
Вернемся к нашей первой программе на Java, но на этот раз добавим в нее комментарии со встроенной документацией:
//: object/Hel1oDate.java import java util.*;
/** Первая программа-пример книги.
* Выводит строку и текущее число.
* ^author Брюс Эккель
* ^author www.MindView net
* (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 означает эту главу) с последующим именем файла1. Последняя строка также завершается комментарием (///:~), обозначающим конец исходного текста программы. Он помогает автоматически извлекать из текста книги программы для проверки компилятором и выполнения.