Студопедия  
Главная страница | Контакты | Случайная страница

АвтомобилиАстрономияБиологияГеографияДом и садДругие языкиДругоеИнформатика
ИсторияКультураЛитератураЛогикаМатематикаМедицинаМеталлургияМеханика
ОбразованиеОхрана трудаПедагогикаПолитикаПравоПсихологияРелигияРиторика
СоциологияСпортСтроительствоТехнологияТуризмФизикаФилософияФинансы
ХимияЧерчениеЭкологияЭкономикаЭлектроника

Документирование исходного кода в Java

Читайте также:
  1. Для контроля исходного уровня знаний
  2. Контроль исходного уровня знаний и умений
  3. По модулю ПМ 01 Документирование хозяйственны операций и ведение бухгалтерского учета имущества организации
  4. Тестовые задания для контроля исходного уровня знаний
  5. Характеристика исходного сырья.

Одной из важнейших частей написания программного обеспечения является документирование создаваемого кода. В Java для этих целей применяется средство, обеспечивающее поддержку на уровне синтаксиса языка программирования – специализированные комментарии. Они начинаются с комбинации символов /** и заканчиваются комбинацией символов */

Часть комментариев автоматически создает среда разработки.

Пример:

/** * Creates new form GUI_application */

Средством обработки внедренных в исходный код комментариев и создания для класса справочных HTML-файлов является инструмент javadoc, входящий в состав JDK. Но в среде NetBeans удобнее пользоваться вызовом через главное меню: Build/Generate Javadoc for "…".Документационные комментарии бывают для:

· Пакетов (пока не функционируют).

· Классов.

· Интерфейсов.

· Пользовательских типов-перечислений (на уровне пакетов пока не функционируют, но можно использовать для типов, заданных в классах).

· Методов.

· Переменных.

Документационные комментарии пишутся непосредственно перед заданием соответствующей конструкции – пакета, класса, интерфейса, типа-перечисления, метода или переменной. Следует учитывать, что по умолчанию документация создается только для элементов, имеющих уровень видимости public или protected.

Пример фрагмента кода с документационными комментариями:

/** * Пример приложения Java с документационными комментариями <br> * В приложении заданы типы-перечисления Monthes и Spring и показано, * как с ними работать. * Кроме того, дан пример использования класса из другого пакета. * @see enumApplication.Monthes Информация о типе-перечислении Monthes * @see enumApplication.Spring * @see enumApplication#m1 * @version Версия 0.1 Первоначальная версия, проверено при компиляции * в среде NetBeans 5.5 * @author Вадим Монахов */public class enumApplication extends javax.swing.JFrame { int i=1;/** * Spring - задает перечисление из 3 весенних месяцев года: march,apr,may. * <ul> * <li>march * <li>apr * <li>may * </ul> * Идентификатор для марта записан отличающимся от соответствующего * идентификатора в перечислении Monthes, а для апреля и мая записаны так * же - чтобы подчеркнуть, что их пространства имен независимы. */ public enum Spring {march,apr,may}; /** * Monthes - задает перечисление из 12 месяцев года: <br> * jan,feb,mar,apr,may,jun,jul,aug,sep,oct,nov,dec <br> * (январь, февраль и т.д.) */ public enum Monthes {jan,feb,mar,apr,may,jun,jul,aug,sep,oct,nov,dec}; Spring spr1= Spring.apr, spr2; /** *Переменная, иллюстрирующая работу с перечислениями */ public Monthes m1,m2=Monthes.mar,m3;

Листинг

Имеется два типа кода внутри блока документационного комментария – HTML-текст и метаданные (команды документации, начинающиеся с символа @ ). Если пишется обычный текст, он рассматривается как HTML-текст, поэтому все пробелы и переносы на новую строку при показе приводятся к одному пробелу. Для того, чтобы очередное предложение при показе начиналось с новой строки, следует вставить последовательность символов <br> , называющуюся тегом HTML. Возможно использование произвольных тегов HTML, а не только тега переноса на новую строку: теги неупорядоченного списка <ul> и <li>, теги гиперссылок, изображений и т.д. В то же время не рекомендуется использовать заголовки и фреймы, поскольку это может привести к проблемам – javadoc создает на основе документационного кода собственную систему заголовков и фреймов. Кроме того, при преобразовании в HTML-документ из документационного кода удаляются символы "*", если они стоят на первом значимом месте в строке (символы пробелов не являются значимыми).

Для более подробного изучения тегов HTML следует читать справочную или учебную литературу по этому языку разметки документов. Соответствующие ссылки и документы можно найти, например, на сайте автора http://barsic.spbu.ru/www/comlan/html_r.html.

Команды документации (символы метаданных):

· @see ("смотри") - применяется для создания в документе гиперссылок на другие комментарии. Можно использовать для любых конструкций (классов, методов и т.д. ). Формат использования: @see ИмяКласса - для класса; @see ИмяКласса.ИмяПеречисления - для типа-перечисления, заданного в классе; @see ИмяКласса#ИмяЧлена - для метода или переменной; для интерфейса - аналогично классу. При этом имя класса или интерфейса может быть либо коротким, либо квалифицировано именем пакета.

· @version ("версия") - информация о версии. Используется для классов и интерфейсов. Формат использования: @version Информация о версии в произвольной форме.

· @author ("автор") - Информация об авторе. Используется для классов и интерфейсов. Формат использования: @author Информация об авторе в произвольной форме. Может включать не только имя, но и данные об авторских правах, а также об электронной почте автора, его сайте и т.д.

· @since ("начиная с") - Информация о версии JDK, начиная с которой введен или работоспособен класс или интерфейс. Формат использования: @since Информация в произвольной форме.

· @param (сокращение от parameter -"параметр") - информация о параметре метода. Комментарий /** @param … */ ставится в месте декларации метода в списке параметров перед соответствующим параметром. Формат использования: @param ИмяПараметра Описание.

· @return ("возвращает") - информация о возвращаемом методом значении и его типе. Формат использования: @return Информация в произвольной форме.

· @throws ("возбуждает исключение") - информация об исключительных ситуациях, которые могут возбуждаться методом. Формат использования: @throws ИмяКлассаИсключения Описание.

· @deprecated ("устаревшее") - информация о том, что данный метод устарел и в последующих версиях будет ликвидирован. При попытке использования таких методов компилятор выдает программисту предупреждение (warning) о том, что метод устарел, хотя и компилирует проект. Формат использования: @deprecated Информация в произвольной форме.

Признаком окончания команды документации является начало новой команды или окончание комментария.

Пример документации, созданной для пакета, из которого взят приведенный выше фрагмент кода:

Рис. 11.27. Головная страница файлов документации

Рис. 11.28. Страница описания элементов пакета java_enum_pkg

Рис. 11.29. Страница описания класса enumApplication

 

Обратите внимание, что в краткой сводке (summary) приводятся только начальные строки соответствующей информации по элементам пакета или класса. Полную информацию можно прочитать после перехода по гиперссылке в описании соответствующего элемента. Поэтому важно, чтобы первые 2-3 строки информации содержали самые важные сведения.


Дата добавления: 2015-09-11; просмотров: 9 | Нарушение авторских прав

Пример 9.1. | Часть 10. Файлы и потоки | Часть 11. Создание приложений Java в интегрированной среде разработки (IDE) NetBeans | Компиляция файлов проекта и запуск приложения | Структура проекта NetBeans | Создание в NetBeans приложения Java с графическим интерфейсом | Редактор экранных форм | Внешний вид приложения | Ведение проектов | Редактирование меню экранной формы |


lektsii.net - Лекции.Нет - 2014-2020 год. (0.012 сек.) Все материалы представленные на сайте исключительно с целью ознакомления читателями и не преследуют коммерческих целей или нарушение авторских прав