Содержание | Предыдущая

ГЛАВА 18

Комментарии документации

Программы на языке Ява могут включать документацию в их исходном коде в специальных комментариях документации (§ 3.7). Такие комментарии могут появляться перед каждым классом или объявлением интерфейса и перед каждым методом, конструктором или объявлением поля. Тогда гипертекст web страницы может быть произведен автоматически из исходного кода программы и этих комментариев документации.

Эта глава дает неофициальное описание комментариев документации. Полная формальная спецификация требовала бы подробного описания тех частей языка гипертекстовой разметки (HTML), которые могут использоваться в пределах комментариев документации и которые находятся вне области действия этой спецификации.

18.1 Текст комментария документации

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

Так, например, в комментарии:

/**XYZ
  ** Initialize to pre-trial defaults.
  123*/

текст комментария содержит три строки. Первая строка состоит из текста "XYZ"; вторая строчка состоит из текста "Initialize to pre-trial defauls." И третья строчка состоит из текста "123"

18.2 HTML в комментарии документации

Текст в комментарии документации может использовать теги HTML для форматирования, за исключением того, что определенные теги <H1>, <H2>, <H3>, <H4>, <H5>, <H6>, и <HR> сохранены для использования генератором документации и не должны использоваться в тексте. Полное описание HTML доступно по адресу http://www.w3.org и также через документационную базу данных Интернета в http://www.internic.net, где документ "Hypertext Markup Language -Version 2.0" T. Berners-Lee и D. Connolly может быть найден как RFC1866.

18.3 Обобщающее предложение и общее описание.

Первое предложение каждого комментария документации должно быть обобщающее предложение, содержащее краткое, но полное описание объявленного объекта. Это предложение заканчивается первой точкой, которая сопровождается пробелом, табуляцией, ограничителем строки или первой помеченной строкой (как определено ниже). Это простое правило означает что первое предложение типа:

This is a simulation of Prof. Knuth's MIX computer.

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

Предложение следующее после обобщающего предложения, но предшествующее первому помеченному абзацу (любому) формирует общее описание части комментария документации.

18.4 Помеченные абзацы

Строчка комментария документации, которая начинается с знака @ сопровождаемого одним из специальных ключевых слов, начинает помеченный абзац. Помеченный абзац также включает любые последующие строки, но не включая первой строки следующего помеченного абзаца или конец комментария документации.

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

Различные виды помеченных абзацев доступны для описания класса и интерфейса и для описания метода, поля, и конструктора.

18.4.1 Тег @see

Следующие примеры - примеры абзацев @see , которые могут использоваться в любом комментарии документации, чтобы указать пересечения ссылки к классу, интерфейсу, методу, конструктору, полю, или URL:

@see java.lang.String
@see String
@see java.io.InputStream;
@see String#equals
@see java.lang.Object#wait(int)
@see java.io.RandomAccessFile#RandomAccessFile(File, String)
@see Character#MAX_RADIX
@see <a href="spec.html">Java Spec</a>

Символ # отделяет имя класса от имени одного из его полей, методов, или конструкторов. Одна из нескольких перезагрузок методов или конструкторов может быть выбрана, включив список заключенных в скобки типов аргумента после имени метода или конструктора .

Комментарий документации может содержать больше, чем один тег @see.

18.4.2 Тег @author

Следующее примеры - примеры помеченных строк @authors, которые могут использоваться в комментариях документации для описания класса и интерфейса:

@author Mary Wollstonecraft
@author Hildegard von Bingen
@author Dorothy Parker

Информация в абзаце @author не имеет никакой специальной внутренней структуры.

Комментарий документации может содержать больше, чем один тег @author. Альтернатива, единственный абзац @author может упоминать несколько авторов:

@author Jack Kent, Peggy Parish, Crockett Johnson,
	James Marshall, Marjorie Weinman Sharmat,
	Robert McCloskey, and Madeleine L'Engle

Однако, мы рекомендуем задавать одного автора в абзаце @author, который позволяет инструментальную обработку документации, чтобы обеспечить правильную пунктуацию во всех случаях.

18.4.3 Тег @version

Следующий пример - пример абзаца @version, который может использоваться в комментариях документации для объявлений класса и интерфейса:

@version 493.0.1beta

Информация в абзаце @version не имеет никакой специальной внутренней структуры.

Комментарий документации может содержать в основном один тег @version.

18.4.4 Тег @param

Следующее примеры - примеры абзацев @param, которые могут использоваться в комментариях документации для объявления метода и конструктора:

@param file the file to be searched
@param pattern
	the pattern to be matched during the search
@param count      the number of lines to print for each match

Информация в абзаце @param должна состоять из имени параметра, сопровождаемого коротким описанием.

Комментарий документации может содержать больше, чем один тег @param. Обычное соглашение состоит в том что если любой абзац @param присутствует в комментарии документации, тогда должен иметься один абзац @param для каждого параметра метода или конструктора, и абзацы @param должны появляться в том порядке, в котором объявлены параметры.

18.4.5 Тег @return

Следующий пример - пример абзаца @return, который может использоваться в комментариях документации для объявлений методов, чьи типы результата не являются типом void:

@return the number of widgets that pass the quality test

Информация в абзаце @return не имеет никакой специальной внутренней структуры. Обычное соглашение состоит в том, что он состоит из короткого описания возвращенного значения.

Комментарий документации может содержать в основном один тег @return.

18.4.6 Тег @exception

Следующее пример - пример абзаца @exception, который может использоваться в комментариях документации для объявлений метода и конструктора:

@exception IndexOutOfBoundsException
				the matrix is too large
@exception UnflangedWidgetException the widget does not
				have a flange, or its flange has size zero
@exception java.io.FileNotFoundException the file
				does not exist

Информация в абзаце @exception должна состоять из имени класса исключения (которое может быть простым именем или квалифицированным именем) сопровождаемый коротким описанием случаев, которые генерируют исключение.

Комментарий документации может содержать больше, чем один тег @exception.

Содержание | Предыдущая