Скачать презентацию
Идет загрузка презентации. Пожалуйста, подождите
Презентация была опубликована 9 лет назад пользователемЛариса Фустова
1 Встроенная документация Java Андрей Дмитриев Инженер-программист Sun Microsystems Февраль 2008
2 2 Документация Необходимость поддержки кода вместе с документацией ведет к необходимости их совмещения. Удобство – одно из требований. > Единый стиль. > Четкая структура. > Удобная навигация. Нужен инструментарий для обработки и формирования документации.
3 3 Программа JavaDoc: введение. Инструментарий. Обзор возможностей.
4 4 Комментарии Различают три вида комментариев: //однострочный комментарий /* Это простой комментарий, который распространяется на несколько строк */ /** Это комментарий, понятный javadoc*/
5 5 Утилита javadoc javadoc [options] [packagenames] [sourcefiles] В набор JDK входит утилита javadoc, которая строит стандартную документацию на основе исходных кодов программ. В случае некорректных данных в комментарии, утилита выдает предупреждение.
6 6 Синтаксис /** Компонент - класс */ public class DocumentPrinter { /** Компонент - переменная */ public int id; //в документацию по умолчанию включаются //только public и protected члены private String excludeFromSpec; /** Компонент - метод */ public void print() {} } Чтобы утилита javadoc обработала комментарии с документацией, комментарии должны быть размещены в определённых местах кода.
7 7 Форматирование /** * *System.out.println(newDate()); * */ Программный код в комментарии может быть отформатирован для легкости восприятия:
8 8 Использование тегов HTML /** Вы можете вставить список: * * Первый элемент * Второй элемент * Третий элемент * */ Поддерживается небольшой набор HTML-тегов, включенных в комментарий:
9 9 Теги – ссылка на другой класс, метод или поле. java.awt.Window#isActive Утилита javadoc поддерживает некоторые специальные теги:
10 10 Теги – указание версии – автор – с какой версии продукта или библиотеки появился класс. Специальный набор тегов может быть включен в документацию класса:
11 11 Теги полей Документация переменных может включать только встроенный HTML код и public class DocumentPrinter { /** Идентификатор класса. #print() */ public int id; public void print() {} }
12 12 Теги методов /** Посылает документ на печатающее устройство. Возвращает значение true} если документ успешно отослан. Printer#getDefaultPrinter() document – документ, предназначенные для печати. true} если документ успешно отослан; * false} в противном случае. IOException при возникновении ошибки ввода-вывода. PrinterException при возникновении ошибки печатающего * устройства. рекомендуется использовать метод * print(Document, Printer) }. */ public boolean print(Document document) {…} Документация метода может включать самый широкий спектр возможностей:
13 13 Теги Название параметра метода и комментарий к Описание возвращаемого Тип бросаемого исключения и описание исключительной Данным тегом помечается не рекомендуемый к использованию Ставится перед названиями классов, ключевых слов и т.п. – для применение стиля Ссылка на место в коде.
14 14 Параметры метода /** studID – уникальный идентификатор студента discID – уникальный идентификатор дисциплины */ public boolean isLearned(int studID, int discID){... } После названия параметра следует указать, что он обозначает:
15 15 Возвращаемое значение /** - true} если дисциплина была изучена студентом; * false} в противном случае. */ public boolean isLearned(int studID, int discID){... } Характеризует значение, возвращаемое методом. Если метод не возвращает ничего (void), данный тег не используется. Если возвращаемый тип – boolean, следует указать в каком случае вернется true, а в каком – false.
16 16 Генерируемые исключения /** ArgumentValueException при некорректных входных * параметрах (идентификатор меньше или равен нулю). */ public boolean isLearned(int studID, int discID){... } Сначала указывается тип исключения. Затем – описание исключительной ситуации – в каком случае исключение может быть сгенерировано.
17 17 Пример документации класса /** * Простой класс для демонстрации dav */ public class SimpleClass { /**Текущее значение экспериментальной переменной */ int value = 0; /** * Метод, демонстрирующий особенности * приведения примитивных типов */ public static void main(String[] args) {…} }
18 18 Документация для пакета классов Описание пакета классов должно содержаться в файле package.html, находящимся в каталоге соответствующего пакета.
19 19 Организация гиперссылок DocumentModel} – данный тег преобразуется в гиперссылку на класс DocumentModel. DocumentModel#export()} –преобразуется в гиперссылку на метод класса DocumentModel. Возможно уточнение метода через указание типов формальных параметров в теге
20 20 Страница Javadoc
21 21 Панель навигации Иерархия классов пакета
22 22 Общие данные о классе Описание конструктора в класса
23 23 Краткая характеристика методов класса Более подробное описание метода Унаследованные методы
24 24 Навигация по методам проекта
25 25 Почему javadoc? Доступность. Простота. > С тимулирует комментировать код. Легкость написания документации – не покидая исходный код. В результате: > стандартное оформление > удобная навигация при помощи гиперссылок
26 26 Правда ли что… В документацию входят все многострочные комментарии для всех классов, методов и полей?
27 Q&A
28 Встроенная документация Java Андрей Дмитриев Инженер-программист Sun Microsystems Февраль 2008
Еще похожие презентации в нашем архиве:
© 2024 MyShared Inc.
All rights reserved.