/**
* Вычисление модуля целого числа.
* Этот метод возвращает
* абсолютное значение аргумента 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 = getWidth();
* 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 = getWidth();
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>, будет помещен в документацию, а первое предложение будет использоваться для краткой характеристики этого пакета.
Лексемы
Итак, мы рассмотрели пробелы (в широком смысле этого слова, т.е. все символы, отвечающие за форматирование текста программы) и комментарии, применяемые для ввода пояснений к коду. С точки зрения программиста они применяются для того, чтобы сделать программу более читаемой и понятной для дальнейшего развития.
С точки зрения компилятора, а точнее его части, отвечающей за лексический разбор, основная роль пробелов и комментариев – служить разделителями между лексемами, причем сами разделители далее отбрасываются и на компилированный код не влияют. Например, все следующие примеры объявления переменной эквивалентны:
// Используем пробел в качестве разделителя.
int x = 3;
// здесь разделителем является перевод строки
int
x
=
3
;
// здесь разделяем знаком табуляции
int x = 3;
/*
* Единственный принципиально необходимый
* разделитель между названием типа данных
* int и именем переменной x здесь описан
* комментарием блочного типа.
*/
int/**/x=3;
Конечно, лексемы очень разнообразны, и именно они определяют многие свойства языка. Рассмотрим все их виды более подробно.
Виды лексем
Ниже перечислены все виды лексем в Java:
* идентификаторы (identifiers);
* ключевые слова (key words);
* литералы (literals);
* разделители (separators);
* операторы (operators).
Рассмотрим их по отдельности.
Идентификаторы
Идентификаторы – это имена, которые даются различным элементам языка для упрощения доступа к ним. Имена имеют пакеты, классы, интерфейсы, поля, методы, аргументы и локальные переменные (все эти понятия подробно рассматриваются в следующих лекциях). Идентификаторы можно записывать символами Unicode, то есть на любом удобном языке. Длина имени не ограничена.