Программирование на Java



Комментарии - часть 3


/** * Вычисление модуля целого числа. * Этот метод возвращает * абсолютное значение аргумента x. */ int getAbs(int x) { if (x>=0) return x; else return -x; }

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

Поскольку в результате создается HTML-документация, то и комментарий необходимо писать по правилам HTML. Допускается применение тегов, таких как <b> и <p> . Однако теги заголовков с <h1> по <h6> и <hr> использовать нельзя, так как они активно применяются javadoc для создания структуры документации.

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

/** * Первое предложение - краткое * описание метода. * <p> * Так оформляется пример кода: * <blockquote> * <pre> * if (condition==true) { * x = getWidht(); * y = x.getHeight(); * } * </pre></blockquote> * А так описывается HTML-список: * <ul> * <li>Можно использовать наклонный шрифт * <i>курсив</i>, * <li>или жирный <b>жирный</b>. * </ul> */ public void calculate (int x, int y) { ... }

Из этого комментария будет сгенерирован HTML-код, выглядящий примерно так:

Первое предложение – краткое описание метода.

Так оформляется пример кода:

if (condition==true) { x = getWidht(); y = x.getHeight(); }

А так описывается HTML-список:

• Можно использовать наклонный шрифт курсив, • или жирный жирный.

Наконец, javadoc поддерживает специальные теги. Они начинаются с символа @. Подробное описание этих тегов можно найти в документации. Например, можно использовать тег @see, чтобы сослаться на другой класс, поле или метод, или даже на другой Internet-сайт.

/** * Краткое описание. * * Развернутый комментарий. * * @see java.lang.String * @see java.lang.Math#PI * @see <a href="java.sun.com">Official * Java site</a> */

Первая ссылка указывает на класс String (java.lang – название библиотеки, в которой находится этот класс), вторая – на поле PI класса Math (символ # разделяет название класса и его полей или методов), третья ссылается на официальный сайт Java.

Комментарии разработчика могут быть записаны перед объявлением классов, интерфейсов, полей, методов и конструкторов. Если записать комментарий /** … */ в другой части кода, то ошибки не будет, но он не попадет в документацию, генерируемую javadoc. Кроме того, можно описать пакет (так называются библиотеки, или модули, в Java). Для этого необходимо создать специальный файл package.html, сохранить в нем комментарий и поместить его в каталог пакета. HTML-текст, содержащийся между тегами <body> и </body>, будет помещен в документацию, а первое предложение будет использоваться для краткой характеристики этого пакета.




Содержание  Назад  Вперед