Встроенная документация Java Андрей Дмитриев Инженер-программист Sun Microsystems Февраль 2008

2 Документация Необходимость поддержки кода вместе с документацией ведет к необходимости их совмещения. Удобство – одно из требований. > Единый стиль. > Четкая структура. > Удобная навигация. Нужен инструментарий для обработки и формирования документации.

3 Программа JavaDoc: введение. Инструментарий. Обзор возможностей.

4 Комментарии Различают три вида комментариев: //однострочный комментарий /* Это простой комментарий, который распространяется на несколько строк */ /** Это комментарий, понятный javadoc*/

5 Утилита javadoc javadoc [options] [packagenames] [sourcefiles] В набор JDK входит утилита javadoc, которая строит стандартную документацию на основе исходных кодов программ. В случае некорректных данных в комментарии, утилита выдает предупреждение.

6 Синтаксис /** Компонент - класс */ public class DocumentPrinter { /** Компонент - переменная */ public int id; //в документацию по умолчанию включаются //только public и protected члены private String excludeFromSpec; /** Компонент - метод */ public void print() {} } Чтобы утилита javadoc обработала комментарии с документацией, комментарии должны быть размещены в определённых местах кода.

7 Форматирование /** * *System.out.println(newDate()); * */ Программный код в комментарии может быть отформатирован для легкости восприятия:

8 Использование тегов HTML /** Вы можете вставить список: * * Первый элемент * Второй элемент * Третий элемент * */ Поддерживается небольшой набор HTML-тегов, включенных в комментарий:

9 Теги – ссылка на другой класс, метод или поле. java.awt.Window#isActive Утилита javadoc поддерживает некоторые специальные теги:

10 Теги – указание версии – автор – с какой версии продукта или библиотеки появился класс. Специальный набор тегов может быть включен в документацию класса:

11 Теги полей Документация переменных может включать только встроенный HTML код и public class DocumentPrinter { /** Идентификатор класса. #print() */ public int id; public void print() {} }

12 Теги методов /** Посылает документ на печатающее устройство. Возвращает значение true} если документ успешно отослан. Printer#getDefaultPrinter() document – документ, предназначенные для печати. true} если документ успешно отослан; * false} в противном случае. IOException при возникновении ошибки ввода-вывода. PrinterException при возникновении ошибки печатающего * устройства. рекомендуется использовать метод * print(Document, Printer) }. */ public boolean print(Document document) {…} Документация метода может включать самый широкий спектр возможностей:

13 Теги Название параметра метода и комментарий к Описание возвращаемого Тип бросаемого исключения и описание исключительной Данным тегом помечается не рекомендуемый к использованию Ставится перед названиями классов, ключевых слов и т.п. – для применение стиля Ссылка на место в коде.

14 Параметры метода /** studID – уникальный идентификатор студента discID – уникальный идентификатор дисциплины */ public boolean isLearned(int studID, int discID){... } После названия параметра следует указать, что он обозначает:

15 Возвращаемое значение /** - true} если дисциплина была изучена студентом; * false} в противном случае. */ public boolean isLearned(int studID, int discID){... } Характеризует значение, возвращаемое методом. Если метод не возвращает ничего (void), данный тег не используется. Если возвращаемый тип – boolean, следует указать в каком случае вернется true, а в каком – false.

16 Генерируемые исключения /** ArgumentValueException при некорректных входных * параметрах (идентификатор меньше или равен нулю). */ public boolean isLearned(int studID, int discID){... } Сначала указывается тип исключения. Затем – описание исключительной ситуации – в каком случае исключение может быть сгенерировано.

17 Пример документации класса /** * Простой класс для демонстрации dav */ public class SimpleClass { /**Текущее значение экспериментальной переменной */ int value = 0; /** * Метод, демонстрирующий особенности * приведения примитивных типов */ public static void main(String[] args) {…} }

18 Документация для пакета классов Описание пакета классов должно содержаться в файле package.html, находящимся в каталоге соответствующего пакета.

19 Организация гиперссылок DocumentModel} – данный тег преобразуется в гиперссылку на класс DocumentModel. DocumentModel#export()} –преобразуется в гиперссылку на метод класса DocumentModel. Возможно уточнение метода через указание типов формальных параметров в теге

20 Страница Javadoc

21 Панель навигации Иерархия классов пакета

22 Общие данные о классе Описание конструктора в класса

23 Краткая характеристика методов класса Более подробное описание метода Унаследованные методы

24 Навигация по методам проекта

25 Почему javadoc? Доступность. Простота. > С тимулирует комментировать код. Легкость написания документации – не покидая исходный код. В результате: > стандартное оформление > удобная навигация при помощи гиперссылок

26 Правда ли что… В документацию входят все многострочные комментарии для всех классов, методов и полей?

Q&A

Встроенная документация Java Андрей Дмитриев Инженер-программист Sun Microsystems Февраль 2008