Javadoc вставляет команды html в созданный документ. Это может быть полезно, например, для форматирования кода (попробуйте самостоятельно посмотреть результат):
/**
Комментарий к классу: Класс HelloWorld
* <pre>
* System.out.println("Hello, World!");
* </pre>
*/
Вы можете вставлять любые тэги html. Это дает практически неограниченные возможности для форматирования документации.
Тэги javadoc (не путать с html тэгами!):
@see: ссылка на другой класс
Все три типа компонентов документации (класс, переменная и метод) могут содержать ярлык @see, который позволяет ссылаться на документацию другого класса. Javadoc генерирует HTML с ярлыком @see, как гиперссылку на другой документ. Форма:
Каждая вставка добавляет гиперссылку, входящую в раздел “See Also”, при генерации документации. Javadoc не проверяет гиперссылки, которые вы даете, чтобы убедится в их правильности.
Наряду со встроенным HTML и ссылками @see, документация класса может включать ярлыки для информации о версии и имени автора.
@version
Форма
@version version-information
в которой version-information - это любая важная для вас информация., которую вы хотите включить. Когда вносится флаг -version в командную строку javadoc, информация о номере версии специально будет включена в генерируемый HTML документ.
@author
Форма:
@author author-information
в которой author-information это, предположительно, ваше имя, но она также может включать ваш электронный адрес или любую другую подходящую информацию. Когда флаг -author вносится в командную строку javadoc, информация об авторе специально включается в генерируемый HTML документ.
Вы можете иметь несколько ярлыков авторства для всего списка авторов, но они будут помещены последовательно. Вся информация об авторах будет собрана вместе в один параграф генерируемого HTML.
@since
Этот флаг позволяет вам указывать версию того кода, с которого началось использование определенной особенности. Вы увидите, что он появится в HTML документации Java для указания версии JDK.
Как и встроенная документация и ссылки @see, методы допускают ярлыки документации для параметров, возвращаемых значений и исключений.
@param
Форма:
@param parameter-name description
в которой parameter-name - это идентификатор в списке параметров, а description - текст, который может продолжаться на последующих строках. Описание считается законченным, когда обнаруживается новый ярлык документации. Вы можете иметь любое число таких ярлыков, предположительно, по одному для каждого параметра.
@return
Форма:
@return description
в которой description дает вам смысл возвращаемого значения. Описание продолжается на последующих строках.
@throws
Исключения – это объекты, которые могут быть “выброшены” из метода, если метод окончится неудачей. Хотя только один объект исключение может появиться при вызове метода, обычно метод может производить любое число исключений различных типов, все они требуют описания. Форма ярлыка исключения следующая:
@throws fully-qualified-class-name description
в которой fully-qualified-class-name дает вам уникальное имя класса исключения, который где-нибудь определен, а description (которое может продолжаться на последующих линиях) говорит вам, почему этот тип исключения может возникнуть при вызове метода.
@deprecated
Это используется для ярлыка особенностей, которые были заменены улучшенными особенностями. Ярлык deprecated советует вам больше не использовать эту определенную особенность, так как когда нибудь в будущем она будет удалена. Метод, помеченный как @deprecated, заставляет компилятор выдавать предупреждение, если он используется.
Пример кода с комментариями из книги Брюса Эккеля [5]:
//: c02:HelloDate.javaimport java.util.*; /** Первая программа - пример Thinking in Java. * Отображает строку и сегодняшнюю дату. * @author Bruce Eckel * @author www.BruceEckel.com * @version 2.0 */public class HelloDate { /** Единственная точка входа для класса и приложения * @param args массив строк аргументов * @return Возвращаемого значения нет * @exception Исключения не выбрасываются */ public static void main(String[] args) { System.out.println("Hello, it's: "); System.out.println(new Date()); }} ///:~
ЗАДАНИЕ: для созданных в работах 1, 3, 4, 5, 6, 7, 8 классов создать документацию с использованием программы javadoc. В документации должны быть описаны ВСЕ классы, их свойства, методы, аргументы методов, возвращаемые значения, исключения (если есть). Кроме того, в работе 4 (расширение класса) обязательно должны присутствовать ссылки на другой класс. Обязательно использование тэга @author. Также обязательно использование хотя бы 4 видов тэгов html в коде для генерации документа.
Вопросы к работе:
1. Что такое комментарий?
2. Для чего нужны комментарии?
3. Какие типы комментариев можно использовать в Java?
4. Имеет ли значение язык, на котором пишется комментарий?
5. Имеет ли значение регистр букв в тэгах javadoc и html?
6.
7. Как генерировать автоматическую документацию с помощью комментариев в IDE ECLIPSE?
8. Как генерировать автоматическую документацию с помощью комментариев в IDE NetBeans?
9. Что такое html?
10. Как вставлять тэги html в код для генерации автодокументации?
