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


         

Первое предложение должно содержать краткое


/** * Вычисление модуля целого числа. * Этот метод возвращает * абсолютное значение аргумента 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>, будет помещен в документацию, а первое предложение будет использоваться для краткой характеристики этого пакета.

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