logo
Методичка Java

2.13. Документирование исходного кода в 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

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

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

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

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

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

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

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