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

0

 

  Комментарии документирования могут содержать тэги (tags), предназначенные для хранения данных специального вида. Наименование каждого тэга начинается с символа @ — как, например, @see или @deprecated. Абзацы текста, обозначенные тэгами, интерпретируются особым образом — в результате будут получены перекрестные ссылки, указывающие на другие документы, сведения об авторах или фрагменты текста иных типов. В этом разделе описаны все тэги документирования, за исключением ©serial, @serialData и @serialField — указанные тэги, имеющие отношение к механизму сериализации объектов, рассмотрены в разделе 15.7.8.

  Текст комментариев, кроме абзацев, помеченных тэгами документирования, трактуется как данные в формате HTML: например, абзацы могут быть созданы с помощью стандартного дескриптора <р>, блоки текста с сохранением признаков форматирования — посредством дескриптора <рге>, и т.п.

 

14.2.1. @see

 

  Тэг @see создает перекрестную ссылку, указывающую на другой документ javadoc. С помощью тэга нетрудно пометить любой идентификатор, хотя тот должен быть описан с достаточной степенью полноты. Для ссылки на член класса, например, обычно можно использовать простое имя. Если, однако, речь идет о перегруженном методе, следует явно указать, какой из вариантов метода имеется в виду, перечислив типы его параметров. Интерфейс или класс, принадлежащие текущему пакету, обозначаются простыми именами, но если необходимо сослаться на тип, определенный в другом пакете, надлежит задать его полное наименование. Для ссылки на член типа используется префикс #, предшествующий имени члена. Так выглядят Различные синтаксически правильные тэги @see:

@see    #getNatne

@see    Attr

@see    com.magi сattr.Attr

@see    com.magi с.attг.Deck#DECK_SIZE

@see    com.magic.attr.Attr#getName

@see    com.magi с.attr.Attr#Attr(String)

@see    com.magic.attr.Attr#Attr(String,   Object)

@see    com.magi сattr

@see <a href="spec.html#attr">Cneu.n<}>HKauHfl Attribute</a>

@see  "The Java Developer’s Almanac"

 

Первый тэг указывает на метод getName, принадлежащий тому же классу или ив терфейсу, который описывается комментарием документирования как таковым, ли бо любому внешнему типу; подобный синтаксис может быть применен и для обозн чения полей. Второй тэг ссылается на класс, определенный в текущем или импорта рованном пакете. В конструкции третьего тэга используется полное имя класса.

   Четыре следующих тэга служат примерами построения ссылок, указывающих на члены типов. Первые два из них иллюстрируют приемы задания полных имен полей (DECK_SIZE) и методов (getName). Наименование метода в последнем случае задается непосредственно, поскольку в составе класса Attr объявлен в точности один метод с именем getName. Два следующих тэга показывают, как можно сослаться на конструкторы класса, — первый указывает на конструктор класса Attr, предусматривающий передачу единственного аргумента типа String, а второй отвечает конструктору с двумя параметрами— String и Object (если в составе класса или интерфейса существует несколько перегруженных версий конструктора или метода, следует перечислить типы аргументов того члена, который имеется в виду).

   Следующий тэг отсылает читателя к определенному пакету (в данном случае — com. magi с. attr).

   Два заключительных варианта тэгов иллюстрируют возможности построения ссылок на другие документы. В первом посредством дескриптора <а> определяется гиперссылка в формате HTML, а во втором для задания наименования документа используется обычная текстовая строка вида ". . .". Подобные тэги удобно применять для ссылки на другие документы, такие как полные спецификации типов.

   Конструкция тэга @see предполагает, что наименование любой из сущностей кода может обладать следующей за ним меткой (label) (это относится ко всем приведенным выше примерам тэгов, за исключением двух последних). Строка метки, если таковая присутствует, заменяет собой наименование сущности в генерируемом документе. Так, например, тэг

@see #getName наименование атрибута

создает ссылку на документ, содержащий описание сущности (в данном случае, метода) getName, но вместо строки "getName" в документ будет помещен заголовок "Наименование атрибута". Обычно удобнее видеть в документации подлинное наименование типа или члена, но подчас полезно использовать и возможность задания текстовой метки.

 

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

По теме:

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