Главная » Java » Внешние файлы документирование в java

0

 

   Не вся документация пакета может быть отнесена к определенному файлу равно как и исходные файлы, — это не единственный источник данных для под! готовки документации. Документация способна содержать и дополнительные элементы, рассмотренные ниже.

 

Файлы обзора и документация пакета

 

   Комментарии документирования связывают справочную информацию с элементами кода в исходных файлах, но сведения о пакете в целом в исходных файлах не содержатся. Приложение javadoc позволяет документировать общие характеристики пакета или набора пакетов с помощью файла package. html и специальных файлов обзора (overview files), представленных в формате HTML.

   Файл package.html располагается в каталоге, отвечающем определенному пакету, и используется при подготовке документации для этого пакета. Во время обработки исходных файлов, относящихся к пакету, часть содержимого файла package.html, расположенная между дескрипторами <body> и </body>, счи-тывается точно так же, как если бы она была размещена внутри обычного комментария документирования (хотя наличие разделителей /**, */ и начальных символов * в строках не требуется).

   В процессе обработки package.html интерпретируются не все тэги— данные, относящиеся к тэгам ©deprecated, ©author и ©version, в документацию пакета вставлены не будут. Как и при считывании обычных комментариев документирования, первое предложение тела комментария пакета трактуется как аннотация к пакету в целом. В тэгах ©see или {©link} следует задавать полные имена сущностей кода — даже для тех классов и интерфейсов, которые принадлежат пакету непосредственно.

   Файлы в формате HTML, заданные в качестве файлов обзора, при подготовке документации обрабатываются таким же образом, как и файл package.html.

 

Каталог doc-files

 

   Программа javadoc способна включить в документацию пакета содержимое подкаталога doc-files каталога пакета. Это средство позволяет снабдить комментарии документирования ссылками на любые необходимые источники данных, такие как изображения, дополнительные файлы HTML и т.д. С его помощью легко, например, создать ссылки из множества комментариев, указывающие на один и тот же документ:

 

@see <a href="doc-files/semantics.html"><t>op&^bHafl семантика</а>

 

либо использовать каталог для хранения файлов полезных графических изображений:

 

Фирма  ‘Рога и  копыта'<птд src="doc-files/logo.gif">

 

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

По теме:

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