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

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

Комментарий разработчика записывается так же, как и блочный. Единственное различие в начальной комбинации символов — для доку­ментации комментарий необходимо начинать с /**. Например:

* Вычисление модуля целого числа.

* Этот метод возвращает

* абсолютное значение аргумента х.

7

int getAbs(intx) { if (х>=0)

return х; else

return -x;

}

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

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

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

j-k-k

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

* <р>

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

* <blockquote>

* <рге>

* if (condition==true) {

x = getWidht(); у = x.getHeight();

* }

* </pre></blockquote>

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

* <ul>

* <П>Можно использовать наклонный шрифт <i>KypcnB</i>,

* <Н>или жирный <Ь>жирный</Ь>.

* </ul> 7

public void calculate (int x, int y) { }