@param имя-параметра описание
где имя-параметра — это идентификатор в списке параметров метода, а описание — текст описания, который можно продолжить на несколько строк. Описание считается завершенным, когда встретится новый тег. Можно записывать любое количество тегов @param, по одному для каждого параметра метода.
©return
Форма использования:
©return описание
где описание объясняет, что именно возвращает метод. Описание может состоять из нескольких строк.
@throws
Исключения будут рассматриваться в главе 9. В двух словах это объекты, которые можно «возбудить» (throw) в методе, если его выполнение потерпит неудачу. Хотя при вызове метода создается всегда один объект исключения, определенный метод может вырабатывать произвольное количество исключений, и все они требуют описания. Соответственно, форма тега исключения такова:
©throws полное-имя-класса описание
где полное-имя-класса дает уникальное имя класса исключения, который где-то определен, а описание (расположенное на произвольном количестве строк) объясняет, почему данный метод способен создавать это исключение при своем вызове.
@deprecated
Тег используется для пометки устаревших возможностей, замещенных новыми и улучшенными. Он сообщает о том, что определенные средства программы не следует использовать, так как в будущем они, скорее всего, будут убраны. В Java SE5 тег @deprecated был заменен директивой @Deprecated (см. далее).
Пример документации
Вернемся к нашей первой программе на Java, но на этот раз добавим в нее комментарии со встроенной документацией:
//: object/Hel1oDate.java import java util.*;
/** Первая программа-пример книги.
* Выводит строку и текущее число.
* ^author Брюс Эккель
* ^author www.MindView net
* (Aversion 4.0 */
public class HelloDate {
/** Точка входа в класс и приложение
* @param args Массив строковых аргументов
* @throws exceptions Исключения не выдаются */
public static void main(String[] args) {
System out.printlnCTIpMBeT. сегодня: "); System.out.println(new DateO);
}
} /* Output. (55* match) Привет, сегодня. Wed Oct 05 14:39:36 MDT 2005 */// ~
В первой строке файла использована моя личная методика помещения специального маркера //: в комментарий как признака того, что в этой строке комментария содержится имя файла с исходным текстом. Здесь указывается путь к файлу (object означает эту главу) с последующим именем файла>1. Последняя строка также завершается комментарием (///:~), обозначающим конец исходного текста программы. Он помогает автоматически извлекать из текста книги программы для проверки компилятором и выполнения.
