Читать «Java 7 (Наиболее полное руководство)» онлайн - страница 18
Ильдар Шаукатович Хабибуллин
Именно так создается документация к JDK.
Добавим комментарии к нашему примеру (листинг 1.2).
Листинг 1.2. Первая программа с комментариями
/**
* Разъяснение содержания и особенностей программы...
* @author Имя Фамилия (автора)
* @version 1.0 (это версия программы)
*/
class HelloWorld{ // HelloWorld — это только имя // Следующий метод начинает выполнение программы
public static void main(String[] args){ // args не используются /* Следующий метод просто выводит свой аргумент * на экран дисплея */
System.out.println("Hello, XXI Сentury World!");
// Следующий вызов закомментирован,
// метод не будет выполняться
// System.out.println("Farewell, XX Сentury!");
}
}
Звездочки в начале строк не имеют никакого значения, они написаны просто для выделения комментария. Пример, конечно, перегружен пояснениями (это плохой стиль), здесь просто показаны разные формы комментариев.
Аннотации
Обратите внимание на комментарий, приведенный в начале листинга 1.2. В него вставлены указания-теги @author и @version утилите javadoc. Просматривая текст этого комментария и встретив какой-либо из тегов, утилита javadoc выполнит предписанные тегом действия. Например, тег @see предписывает сформировать гиперссылку на другой документ HTML, а тег @deprecated, записанный в комментарий перед методом, вызовет пометку этого метода в документации как устаревшего.
Идея давать утилите предписания с помощью тегов оказалась весьма плодотворной. Кроме javadoc были написаны другие утилиты и целые программные продукты, которые вводят новые теги и используют их для своих целей. Например, программа XDoclet может автоматически создавать различные конфигурационные файлы, необходимые для работы сложных приложений. Разработчику достаточно вставить в свою программу комментарии вида /**...*/ с тегами специального вида и запустить утилиту Xdoclet, которая сгенерирует все необходимые файлы.
Использование таких утилит стало общепризнанной практикой, и, начиная с пятой версии Java SE, было решено ввести прямо в компилятор возможность обрабатывать теги, которые получили название
Несколько аннотаций, количество которых увеличивается с каждой новой версией JDK, объявлено прямо в компиляторе. Ими можно пользоваться без дополнительных усилий. Мы будем вводить их по мере надобности. Кроме них разработчик может объявить и использовать в своем приложении свои аннотации. Как это делается, рассказано в
Константы
В языке Java можно записывать константы различных типов в разных видах. Форма записи констант почти полностью заимствована из языка С. Перечислим все разновидности констант.
