Первое предложение должно содержать краткое резюме всего комментария. В дальнейшем оно будет использовано как пояснение этой функции в списке всех методов класса (ниже будут описаны все конструкции языка, для которых применяется комментарий разработчика).
Поскольку в результате создается HTML-документация, то и комментарий необходимо писать по правилам HTML. Допускается применение тегов, таких как <Ь> и <р>. Однако теги заголовков с <h1 > по <h6> и <hr> использовать нельзя, так как они активно применяются javadoc для создания структуры документации.
Символ * в начале каждой строки и предшествующие ему пробелы и знаки табуляции игнорируются. Их можно не использовать вообще, но они удобны, когда необходимо форматирование, скажем, в примерах кода.
/**
* Первое предложение - краткое описание метода.
* <р>
* Так оформляется пример кода:
* <blockquote>
* <рге>
* if (condition==true) {
x = ge1VVidht{);
* у = x.getHeightO; *}
* </pre></blockquote>
* Атак описывается HTML-список:
* <ul>
* <П>Можно использовать наклонный шрифт <1>курсив</1>,
* <Н>или жирный <Ь>жирный</Ь>.
* </и1> 7
public void calculate (Int x, Int y) {
Из этого комментария будет сгенерирован HTML-код, выглядящий примерно так:
Первое предложение - краткое описание метода.
Так оформляется пример кода:
if (condition==true) { x = getWidht{); y = x.getHeight();
}
A так описывается HTML-список:
• Можно использовать наклонный шрифт курсив,
• или жирный жирный.
Наконец, javadoc поддерживает специальные теги. Они начинаются с символа @. Подробное описание этих тегов можно найти в документации. Например, можно использовать тег @see, чтобы сослаться на другой класс, поле или метод, или даже на другой Internet-сайт
Первая ссылка указывает на класс String (Java.lang - название библиотеки, в которой находится этот класс), вторая - на поле Р1 класса Math (символ # разделяет название класса и его полей или методов), третья ссылается на официальный сайт Java.
Комментарии разработчика могут быть записаны перед объявлением классов, интерфейсов, полей, методов и конструкторов. Если записать комментарий /**...*/ в другой части кода, то ошибки не будет, но он не попадет в документацию, генерируемую javadoc. Кроме того, можно описать пакет (так называются библиотеки, или модули, в Java). Для этого необходимо создать специальный файл pacl<age.litml, сохранить в нем комментарий и поместить его в каталог пакета. HTML-текст, содержащийся между
тегами <body> и </body>, будет помещен в документацию, а первое предложение будет использоваться для краткой характеристики этого пакета.
Все классы стандартных библиотек Java поставляются в виде исходного текста и можно увидеть, как хорошо они комментированы. Стандартная документация по этим классам сгенерирована утилитой javadoc. Для любой программы также можно подготовить подобное описание, необходимы лишь грамотные и аккуратные комментарии в исходном коде. IQ)OMe того,Java предоставляет возможность генерировать с помощью javadoc документацию с нестандартным внешним видом.
Лексемы
Итак, мы рассмотрели пробелы (в широком смысле этого слова, т.е. все символы, отвечающие за форматирование текста программы) и комментарии, применяемые для ввода пояснений к коду. С точки зрения программиста они применяются для того, чтобы сделать программу более читаемой и понятной для дальнейшего развития.
С точки зрения компилятора, а точнее его части, отвечающей за лексический разбор, основная роль пробелов и комментариев — служить разделителями между лексемами, причем сами разделители далее отбрасываются и на компилированный код не влияют, например, все следующие примеры объявления переменной эквивалентны:
// Используем пробел в качестве разделителя, int X = 3 ;
// здесь разделителем является перевод строки int
X
// здесь разделяем знаком табуляции intx = 3;
/*
* Единственный принципиально необходимый разделитель
* между названием типа данных int и именем переменной х
* здесь описан комментарием блочного типа.
int/*Vx=3;
Конечно, лексемы очень разнообразны, и именно они определяют многие свойства языка. Рассмотрим все их виды более подробно.
