JavaDoc и комментарии
Наибольшая проблема, связанная с документированием кода - поддержка этой самой документации. Если документация и код разделены, то возникают трудности, связанные с необходимостью внесения изменений в соответствующие разделы сопроводительной документации всякий раз при изменении программного кода. Java предлагает решение - связать код с документацией, поместив всё в один файл.
Java комментарии необходимы для комментирования программы и для составления или оформления сопроводительной документации. Существует специальный синтаксис для оформления документации в виде комментариев и инструмент для выделения этих комментариев в удобную форму. Инструмент называется JavaDoc. Обрабатывая файл с исходным кодом программы, он выделяет помеченную документацию из комментариев и связывает её с именами соответствующих классов или методов. Таким образом, затратив минимум усилий на оформление комментариев, Вы можете получить хорошую документацию к своей программе.
Результатом работы javadoc является html-файл, который можно просмотреть любым браузером. Библиотеки Java обычно документируют именно таким способом, именно поэтому при разработке программ удобно использовать JDK с комментированным для JavaDoc исходным кодом библиотек вместо JRE, где исходники отсутствуют.
Java имеет три типа комментариев. Первые два типа: //... и /*...*/ являются обычными комментариями. Третий тип называется комментарием документации. Такой комментарий начинается с последовательности символов /** и заканчивается последовательностью */. Комментарии документации позволяют добавлять в программу информацию о ней самой. В командной строке с помощью утилиты javadoc (входящей в состав JDK) эту информацию можно извлекать и помещать в html-файл.
Утилита javadoc позволяет вставлять html-тэги и использовать специальные ярлыки (дескрипторы) документирования. html-тэги заголовков не используют, чтобы не нарушать стиль файла, сформированного утилитой.
Дескрипторы JavaDoc, начинающиеся со знака @, называются автономными и должны помещаться с начала строки комментария (лидирующий символ * игнорируется). Дескрипторы, начинающиеся с фигурной скобки, например {@code}, называются встроенными и могут применяться внутри описания.
Комментарии документации применяют для документирования классов, интерфейсов, полей (переменных), конструкторов и методов. В каждом случае комментарий должен находиться перед документируемым элементом. Обычно на предыдущей строке.
Для документирования переменной можно использовать следующие дескрипторы:
@see, @serial, @serialField, {@value}, @deprecated.
Для классов и интерфейсов можно использовать дескрипторы:
@see, @author, @deprecated, @param, @version.
Методы можно документировать с помощью дескрипторов:
@see, @return, @param, @deprecated, @throws, @serialData, {@inheritDoc}, @exception.
Дескрипторы {@link}, {@docRoot}, {@code}, {@literal}, @since, {@linkplain} могут применяться где угодно.
После начальной комбинации символов /** располагается текст, являющийся главным описанием класса, переменной или метода. Далее можно вставлять различные дескрипторы. Каждый дескриптор @ должен стоять первым в строке. Несколько дескрипторов одного и того же типа необходимо группировать вместе. Встроенные дескрипторы (начинаются с фигурной скобки) можно помещать внутри любого описания.
Утилита javadoc в качестве входных данных принимает файл с исходным кодом программы. Генерирует несколько html-файлов, содержащих документацию по этой программе. Информация о каждом классе будет содержаться в отдельном html-файле. Кроме того, создаётся дерево индексов и иерархии. Могут быть сгенерированы и другие html-файлы.
В средах разработки Netbeans и Eclipse генерировать документацию можно используя соответствующую команду для проекта. Также сгенерировать документацию можно командой из консоли.
Описание дескрипторов:
@author описание - документирует автора класса. При вызове утилиты javadoc в командной строке нужно задать опцию -author, чтобы включить поле в html-документацию.
{@code фрагмент_кода} - позволяет встраивать в комментарий текст (фрагмент кода). Этот текст будет отображаться с помощью шрифта кода без последующей обработки в html.
@deprecated описание - определяет, что класс, интерфейс или член класса является устаревшим. Рекомендуется включать дескрипторы @see или {@link} для того, чтобы информировать программиста о доступных альтернативных вариантах. Может использоваться для документирования переменных, методов и классов.
{@docRoot} - определяет путь к корневому каталогу текущей документации.
@exception имя_исключения пояснение - описывает исключение для данного метода. Здесь имя_исключения указывает полное имя исключения, а пояснение представляет строку, которая описывает, в каких случаях может возникнуть данное исключение. Может использоваться только для документирования методов.
{@inheritDoc} - наследует комментарий от непосредственного суперкласса.
{@link пакет.класс#элемент текст} - встраивает ссылку на дополнительную информацию. При отображении текст (если присутствует) используется в качестве имени ссылки.
{@linkplain пакет.класс#элемент текст} - встраивает ссылку. Ссылка отображается шрифтом основного текста.
{@literal описание} - позволяет встраивать текст в комментарий. Этот текст отображается "как есть" без последующей обработки html.
@param имя_параметра описание - документирует параметр для метода или параметр-тип для класса или интерфейса. Может использоваться только для документирования метода, конструктора, обобщённого класса или интерфейса.
@return пояснение - описывает возвращаемое значение метода.
@see ссылка и @see пакет.класс#элемент текст - обеспечивает ссылку на дополнительную информацию.
@serial описание - определяет комментарий для поля, сериализируемого по умолчанию.
@serialData описание - документирует данные, записанные с помощью методов writeObject и writeExternal.
@serialField имя тип описание - для класса, реализующего Serializable, дескриптор обеспечивает комментарий для компонента ObjectStreamField. Здесь имя представляет имя поля, тип представляет его тип, а описание - комментарий для данного поля.
@since выпуск - показывает, что класс или элемент класса был впервые представлены в определённом выпуске. Здесь выпуск представляет строку, в которой указан выпуск или версия, начиная с которого эта особенность стала доступной.
@throws имя_исключения пояснение - имеет то же назначение, что и дескриптор @exception.
{@value} - отображает значение следующей за ним константы, которой должно являться поле static.
{@value пакет.класс#поле} - отображает значение определённого поля static.
@version информация - представляет информацию о версии (как правило, номер). При выполнении утилиты javadoc в командной строке нужно указать опцию -version, чтобы этот дескриптор включить в html-документацию.
Далее
