Главная » Java » Анатомия комментария документирования Java

0

 

   Начало комментария документирования отмечается тремя символами /** завершается он символами */. Каждый комментарий служит для описания еле дующего за ним объявления. Начальные символы * в строках комментария игнорируются, так же как и предшествующие им символы пробела. Первое предложение комментария обычно представляет собой аннотацию, кратко поясняющую назначение объявления; под "предложением" понимается весь текст вплоть до первого символа точки, за которым следует пробел. Рассмотрим такой комментарий документирования:

/**

* Реализация метода дихотомии

 * для решения задачи трех станков.  

*/

public void schedulerO  throws BadlnputDataException;

 

Аннотацией метода scheduler будет предложение "Реализация метода дихотомии для решения задачи трех станков". Первое предложение комментария должно быть кратким, внятным и содержательным.

   Часто внутрь комментария вкладывают дескрипторы HTML, которые содержат директивы форматирования или гиперссылки, указывающие на иные документы. При написании комментариев разрешается пользоваться почти всеми доступными дескрипторами HTML, за исключением тэгов заголовков <hl>, <h2> и т.д., которые зарезервированы генераторами документации для собственных целей. Чтобы вставить в комментарий символы <, > или &, следует использовать инструкции &lt;, &gt; или &amp; соответственно. Если в начало строки комментария требуется вставить символ @, надлежит применить инструкцию &#064; — в противном случае указанный символ будет воспринят как начало тэга комментария (подробно об этом рассказывается в следующем разделе).

   Программами подготовки документации обрабатываются только такие коммента

рии, которые непосредственно предшествуют объявлению класса, интерфейса, кон-

структора, метода или поля. Если комментарий и текст, разъяснению которого он

посвящен, разделены некими строками, за исключением пробелов или других ком

ментариев, такой комментарий к рассмотрению принят не будет. Пусть, например,

между комментарием в верхней части текста файла и служебным словом class, за

дающим начало объявления класса, подлежащего комментированию, расположена

директива package или import — этот комментарий будет проигнорирован. Ком

ментарий, предшествующий выражению одновременного объявления нескольких

полей, относится ко всем этим полям, поэтому при использовании комментариев по

добные составные конструкции объявлений обычно не применяют.          

   Если для унаследованного метода комментарий не задан, метод "наследует соответствующий комментарий из объявления базового типа. Информативность такого комментария нередко вполне достаточна, особенно если класс реализую интерфейс, — реализованные методы зачастую не делают ничего такого, о чем бы не сообщал комментарий из состава объявления базового интерфейса, либо,меньшей  мере,   ничего,   заслуживающего  особого   внимания.   Полагаясь  на

детва  "наследования"  комментариев  документирования,   вы,   тем  не  менее,

° лжны   предоставить   читателю   простой   комментарий,   свидетельствующий   о

что комментарий документирования будет взят из объявления базового ти-

чтобы не складывалось впечатление, что о комментарии просто забыли:

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

public void schedulerO  throws BadlnputDataException  {

// …

}

Если метод одновременно наследует комментарии из состава базового класса и базового интерфейса, программой подготовки документации будет взят комментарий из объявления интерфейса.

 

 

 

 

Источник: Арнолд, Кен, Гослинг, Джеймс, Холмс, Дэвид. Язык программирования Java. 3-е изд .. : Пер. с англ. – М. : Издательский дом «Вильяме», 2001. – 624 с. : ил. – Парал. тит. англ.

По теме:

  • Комментарии