Опубликован: 04.12.2009 | Доступ: свободный | Студентов: 8414 / 657 | Оценка: 4.30 / 3.87 | Длительность: 27:27:00
Лекция 2:

Объектно-ориентированное проектирование и платформа NetBeans

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

Одной из важнейших частей написания программного обеспечения является документирование создаваемого кода. В 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 Информация в произвольной форме.

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

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

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

увеличить изображение
Рис. 2.34. Головная страница файлов документации
Страница описания элементов пакета java_enum_pkg

увеличить изображение
Рис. 2.35. Страница описания элементов пакета java_enum_pkg
Страница описания класса enumApplication

увеличить изображение
Рис. 2.36. Страница описания класса enumApplication

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

Полетаев Дмитрий
Полетаев Дмитрий
Не очень понятно про оболочечные Данные,ячейки памяти могут наверно размер менять,какое это значение те же операции только ячейки больше,по скорости тоже самое
Максим Старостин
Максим Старостин

Код с перемещением фигур не стирает старую фигуру, а просто рисует новую в новом месте. Точку, круг.