Как пользоваться javadoc – Java комментарии — Javadoc

Pro Java: Комментарии документации – Javadoc

Наибольшая проблема, связанная с документированием кода – поддержка этой документации. Если документация и код разделены, возникают трудности, связанные с необходимостью внесения изменений в соответствующие разделы сопроводительной документации всякий раз при изменении программного кода. Среда разработки предлагает решение – связать код с документацией, поместив всё в один файл.

Java комментарии необходимы для комментирования программы и для составления или оформления документации. Существует специальный синтаксис для оформления документации в виде комментариев и инструмент для выделения этих комментариев в удобную форму. Инструмент называется javadoc. Обрабатывая файл с исходным текстом программы, он выделяет помеченную документацию из комментариев и связывает с именами соответствующих классов или методов. Таким образом, затратив минимум усилий на оформления комментариев, можно получить хорошую документацию к программе.

На выходе javadoc получается HTML файл, который можно просмотреть любым веб-обозревателем. Этот инструмент позволяет создавать и поддерживать файлы с исходным текстом программы и, при необходимости, генерировать сопроводительную документацию. Библиотеки Java обычно документируются именно таким способом, именно поэтому при разработке программ удобно использовать JDK с комментированным для javadoc исходным текстом библиотек вместо JRE, где исходники отсутствуют.

Java имеет три типа комментариев. Первые два типа: //… и /*…*/. Третий тип называется комментарием документации. Такой комментарий начинается с последовательности символов /** и заканчивается последовательностью */. Комментарии документации позволяют добавлять в программу информацию о ней самой. С помощью утилиты javadoc (входящей в состав JDK) эту информацию можно извлекать и помещать в НТМL ­файл.

Утилита javadoc позволяет вставлять HTML тэги и использовать специальные ярлыки (дескрипторы) документирования. НТМL тэги заголовков не используют, чтобы не нарушать стиль­файла, сформированного утилитой.

Дескрипторы javadoc, начинающиеся со знака @, называются автономными и должны помещаться с начала строки комментария (лидирующий символ * игнорируется). Дескрипторы, начинающиеся с фигурной скобки, например {@code}, называются встроенными и могут применяться внутри описания.

Комментарии документации применяют для документирования классов, интерфейсов, полей (переменных), конструкторов и методов. В каждом случае комментарий должен находиться перед документируемым элементом.
Для документирования переменной можно использовать следующие дескрипторы:

@see, @serial, @serialField, {@value}, @deprecated.
Для классов и интерфейсов можно использовать дескрипто­ры:
@see, @author, @deprecated, @param, @version.
Методы можно документировать с помощью дескрипторов:
@see, @return, @param, @deprecated, @throws, @serialData, {@inheritDoc}, @ехсерtiоn.

Дескрипторы {@link}, {@docRoot}, {@code}, {@literal}, @since, {@linkplain} могут применяться где угодно.

 

Общая форма комментариев

После начальной комбинации символов /** располагается текст, являющийся главным описанием класса, переменной или метода. Далее можно вставлять различные дескрипторы. Каждый дескриптор @ должен стоять первым в строке. Несколько дескрипторов одного и того же типа необходимо группировать вместе.

Java комментарии — Javadoc

Встроенные дескрипторы (начинаются с фигурной скобки) можно помещать внутри любого описания.

Утилита javadoc в качестве входных данных принимает файл с исходным кодом программы. Генерирует несколько НТМL ­файлов, содержащих документацию по этой программе. Информация о каждом классе будет содержаться в отдельном НТМL файле. Кроме того, создается дерево индексов и иерархии. Могут быть сгенерированы и другие НТМL­ файлы.

В среде Eclipse генерировать документацию можно используя команду меню Project/Generate Javadoc…

 

Дескрипторы javadoc

@author описание
Документирует автора класса. При вызове утилиты javadoc нужно задать
опцию -author, чтобы включить поле в НТМL документацию.

{@code фрагмент_кода}
Позволяет встраивать в комментарий текст (фрагмент кода). Этот текст будет отображаться с помощью шрифта кода без последующей обработки в НТМL.

@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, чтобы этот дескриптор включить в НТМL документацию.

rpilot62.ru

Pro Java: Комментарии документации – Javadoc

Здесь коротенько рассмотрим работу с комментариями документации на примере программ AdvancedHello.java и моего пакета pro.java.util содержащего класс Print.java.

Чтобы не описывать все тэги javadoc я просто дам линки на ресурсы где об этом можно почитать, хотя вы можете это нагуглить и сами. Тут я приведу только примеры использования. И так Print.java в студию!

Javadoc комментарии вставляются перед классом, методом или переменной. И соответственно документируют эти элементы при помощи простого описания, различных javadoc тэгов (например

@param, @version и т.п.), а так же обычных html тэгов.

В приведенном примере использованы html тэги <br> для перехода на новую строку.

Следует так же отметить, что программа генерации комментариев обрабатывает только документирующие комментарии для классов и членов классов с уровнем доступа public и protected по умолчанию.

Это логично потому, что только к ним есть доступ извне и они могут интересовать программиста использующего вашу библиотеку. К private методам и полям он доступа не имеет. Хотя все же эти поля можно включить в документацию используя флаг –private в команде javadoc. Хотя зачем это может быть нужно не особо понятно.

Результатом работы программы javadoc является html файл в том же формате что и вся остальная документация для Java.

Сразу приведу ссылки на документацию по javadoc на сайте Oracle. А так же ссылку на ту же документацию переведенную машинным переводом на русский язык. Хоть это и смешно, но может кому-то  тоже сгодится.

Как видите документация достаточно обширна и всю ее тут приводить просто не имеет ни какого смысла. А вот что действительно будет полезно так это практика создания работающей javadoc в проекте.

Eclipse позволяет сразу же видеть как будут отображаться ваши javadoc комментарии. Для этого достаточно поместить курсор на javadoc комментарий и перейти на вкладку @Javadoc в Eclipse.

И после того, как мы правильно подключим комментарии к нашему проекту мы можем наблюдать в нем уже вот такое при наведении курсора на наш класс Print или его методы print, println printf:

И так существует два основных метода подключения документации к проекту:

• включение исходных текстов в jar файл
• генерация документации при помощи javadoc и подключение их к проекту

Включение исходных файлов в jar это самый простой способ, но не самый правильный. Так как чаще всего я думаю вы не захотите включать свои исходники в jar файл.

Второй способ чуть сложнее, но более правильный – это сгенерировать документацию и поставлять ее отдельно для желающих.

И так начнем с первого способа. Одновременно с ним мы так же узнаем как подключать свои или сторонние библиотеки java к своему проекту в Eclipse.

И так используем первый способ. Генерируем jar файл с библиотекой и включаем в него исходные тексты. Правый клик по проекту и затем выбираем Export.

Далее

Далее

Далее

Далее

Далее, чтобы показать как подключать данную библиотеку, я ее отключил от проекта AdvancedHello и поэтому на нем светятся красные крестики, так как проект не видит библиотеку.

Подключение библиотеки Java к проекту в Eclipse.

И так, правый клик по проекту AdvancedHello, к которому мы подключаем библиотеку

Выбираем подключаемую библиотеку. Красный восклицательный знак стоит потому, что это файл у меня стоит под контролем версий и еще пока не закоммичен. У вас скорей всего восклицательного знака на иконке файла не будет. И вообще забейте пока на это.

Далее видим нашу библиотеку как добавленную и жмем ОК.

Красный крестик у проекта исчез, так как библиотека найдена. Ну и собственно видим в работе наши javadoc комментарии.

Теперь посмотрим что же внутри сгенерированного файла ProJava.jar. Jar это на самом деле просто zip архив.

И видим что внутри jar архива лежит как скомпилированный класс Print.class так и его исходники Print.java, которые мы можем посмотреть:

В большинстве случаев такой вариант не очень хорошая идея. Так как это увеличивает размер jar файла, а так же раскрывает ваши исходные тексты, которыми вы возможно не захотите делится.

Поэтому сейчас рассмотрим другой вариант: генерацию документации как html файлов их архивирование и подключение к проекту. Так же для чистоты эксперимента, нам надо будет перекомпилировать нашу библиотеку ProJava.jar чтобы исключить из нее исходные тексты.

Перегенерим библиотеку. Весь процесс такой же, как уже описывал за исключением того, что надо снять одну галку

Далее все так же как было.

Теперь проверяем, что javadoc комментарии не доступны в проекта AdvancedHello

Ну и быстренько посмотрим внутрь архива ProJava.jar

Теперь там только один наш бинарный файл Print.class, собственно поэтому javadoc комментарии и недоступны в проекте AdvancedHello.java.

Теперь сгенерируем документацию при помощи утилиты javadoc. Для этого я создал специальную папку doc на том же уровне что и src и bin. Дабы был порядок.

Теперь собственно идем в подпапку где лежит наш исходник Print.java и генерируем документацию командой:

javadoc -d C:\Git\StudyingJava\ProJava\doc Print.java

Собственно в этой команде мы указали куда сложить документацию (C:\Git\StudyingJava\ProJava\doc) и из какого файла ее сгенерировать (Print.java). И вот что у нас получилось в подкаталоге doc:

Теперь выделяем все эти файлы и папочку pro и создаем zip архив из всего этого хозяйства, удалив после архивации все эти файлики.

Теперь подкаталог doc выглядит вот так:

Все! Далее подключаем эту документацию к нашему проекту AdvancedHello.java. Для этого правый клик по проекту и погнали…

Видим это и раскрываем узел ProJava.jar

Указываем путь к нашему архиву.

И можем нажать кнопку Validate… чтобы убедиться что все хорошо.

Жмем два раза ОК и должны увидеть такое

То есть мы подключили javadoc к нашей импортированной библиотеке. Опять жмем ОК и проверяем работу подключенных javadoc комментариев.

Все работает. Правда выглядит чуток по другому.

Мы так же можем посмотреть эту документацию в html формате. Можно извлечь все обратно из архива в какой-нибудь подкаталог или же посмотреть прямо из архива кликнув на файле index.html.

Вот так все красивенько выглядит в бразузере

Все на этом по javadoc все если надо больше гугль в помощь!

Этот пример можно будет найти в коммите 31e057b. В следующих коммитах я удалю эти javadoc комментарии, так как они мне не нужны. И кроме того есть такое высказывание, что код должен объяснять сам себя, то есть комментариев должно быть по минимуму. Но это вообще отдельная тема.

Вообще комментировать текст полезно, так как если приходится возвращаться к коду через долгий промежуток времени, то комменты выручают. Но в случае этой небольшой библиотеки комментарии не нужны, так как код и так простой и понятный.

А если они вам нужны то смотрите в упомянутом коммите или же в коммите перед ним.

Как пользоваться Git читайте тут. Если это пока сложно, то забейте на это и смотрите исходники прямо через веб.

pr0java.blogspot.com

java — Как написать Javadoc свойств?

Я делаю оба, чему способствует автозаполнение Eclipse.

Сначала я документирую свойство:

/**
 * The {@link String} instance representing something.
 */
private String someString;

Затем я копирую и вставляю это в getter:

/**
 * The {@link String} instance representing something.
 */
public String getSomeString() {
    return someString;
}

С eclipse операторы @return имеют автозаполнение — поэтому я добавляю слово «Gets», строчный «t» и скопируйте предложение в нижнем регистре «t». Затем я использую @return (с автозаполнением Eclipse), вставляю предложение, а затем задерживаю T в возврате. Затем он выглядит следующим образом:

/**
 * Gets the {@link String} instance representing something.
 * @return The {@link String} instance representing something.
 */
public String getSomeString() {
    return someString;
}

Наконец, я копирую эту документацию в установщик:

/**
 * Gets the {@link String} instance representing something.
 * @return The {@link String} instance representing something.
 */
public void setSomeString(String someString) {
    this.someString = someString;
}

Затем я изменяю его и с автозаполнением Eclipse вы можете получить не только тег @param, но также имя параметра:

/**
 * Sets the {@link String} instance representing something.
 * @param someString The {@link String} instance representing something.
 */
public void setSomeString(String someString) {
    this.someString = someString;
}

Тогда, я закончил. На мой взгляд, этот шаблон делает намного проще, в конечном счете, не только напомнить себе, что означает свойство через повторение, но и облегчает добавление дополнительных комментариев к получателю и сеттеру, если вы хотите добавить сторону эффекты (такие как отсутствие нулевых свойств, поворот строк в верхний регистр и т.д.). Я исследовал создание плагина Eclipse для этой цели, но я не смог найти соответствующую точку расширения для JDT, поэтому я сдался.

Обратите внимание, что предложение может не всегда начинаться с T — оно только первая буква должна быть некапитализирована/рекапитализована при вклеивании.

qaru.site

Java комментарии | Javadoc | Интернет технологии | Статьи | Программирование Realcoding.Net

Наибольшая проблема, связанная с документированием кода – поддержка этой документации. Если документация и код разделены, возникают трудности, связанные с необходимостью внесения изменений в соответствующие разделы сопроводительной документации всякий раз при изменении программного кода. Среда разработки предлагает решение – связать код с документацией, поместив всё в один файл.

Java комментарии необходимы для комментирования программы и для составления или оформления документации. Существует специальный синтаксис для оформления документации в виде комментариев и инструмент для выделения этих комментариев в удобную форму. Инструмент называется javadoc. Обрабатывая файл с исходным текстом программы, он выделяет помеченную документацию из комментариев и связывает с именами соответствующих классов или методов. Таким образом, затратив минимум усилий на оформления комментариев, можно получить хорошую документацию к программе.

На выходе javadoc получается HTML файл, который можно просмотреть любым веб-обозревателем. Этот инструмент позволяет создавать и поддерживать файлы с исходным текстом программы и, при необходимости, генерировать сопроводительную документацию. Библиотеки Java обычно документируются именно таким способом, именно поэтому при разработке программ удобно использовать JDK с комментированным для javadoc исходным текстом библиотек вместо JRE, где исходники отсутствуют.

Java имеет три типа комментариев. Первые два типа: //… и /*…*/. Третий тип называется комментарием документации. Такой комментарий начинается с последовательности символов /** и заканчивается последовательностью */. Комментарии документации позволяют добавлять в программу информацию о ней самой. С помощью утилиты javadoc (входящей в состав JDK) эту информацию можно извлекать и помещать в НТМL ­файл.

Утилита javadoc позволяет вставлять HTML тэги и использовать специальные ярлыки (дескрипторы) документирования. НТМL тэги заголовков не используют, чтобы не нарушать стиль­файла, сформированного утилитой.

Дескрипторы javadoc, начинающиеся со знака @, называются автономными и должны помещаться с начала строки комментария (лидирующий символ * игнорируется). Дескрипторы, начинающиеся с фигурной скобки, например {@code}, называются встроенными и могут применяться внутри описания.

Комментарии документации применяют для документирования классов, интерфейсов, полей (переменных), конструкторов и методов. В каждом случае комментарий должен находиться перед документируемым элементом.
Для документирования переменной можно использовать следующие дескрипторы:

@see, @serial, @serialField, {@value}, @deprecated.
Для классов и интерфейсов можно использовать дескрипто­ры:
@see, @author, @deprecated, @param, @version.
Методы можно документировать с помощью дескрипторов:
@see, @return, @param, @deprecated, @throws, @serialData, {@inheritDoc}, @ехсерtiоn.

Дескрипторы {@link}, {@docRoot}, {@code}, {@literal}, @since, {@linkplain} могут применяться где угодно.

 

Общая форма комментариев

После начальной комбинации символов /** располагается текст, являющийся главным описанием класса, переменной или метода. Далее можно вставлять различные дескрипторы. Каждый дескриптор @ должен стоять первым в строке. Несколько дескрипторов одного и того же типа необходимо группировать вместе. Встроенные дескрипторы (начинаются с фигурной скобки) можно помещать внутри любого описания.

Утилита javadoc в качестве входных данных принимает файл с исходным кодом программы. Генерирует несколько НТМL ­файлов, содержащих документацию по этой программе. Информация о каждом классе будет содержаться в отдельном НТМL файле. Кроме того, создается дерево индексов и иерархии. Могут быть сгенерированы и другие НТМL­ файлы.

В среде Eclipse генерировать документацию можно используя команду меню Project/Generate Javadoc…

 

Дескрипторы javadoc

@author описание
Документирует автора класса. При вызове утилиты javadoc нужно задать
опцию -author, чтобы включить поле в НТМL документацию.

{@code фрагмент_кода}
Позволяет встраивать в комментарий текст (фрагмент кода). Этот текст будет отображаться с помощью шрифта кода без последующей обработки в НТМL.

@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, чтобы этот дескриптор включить в НТМL документацию.

Автор материала: life-prog.ru

www.realcoding.net

Теория и практика Java: Мне нужно задокументировать ЭТО?

Теория и практика Java

Благо и бремя интегрированной документации а ля Javadoc

Брайан Гетц
Опубликовано 09.02.2007

Серия контента:

Этот контент является частью # из серии # статей: Теория и практика Java

https://www.ibm.com/developerworks/ru/views/global/libraryview.jsp?series_title_by=Теория+и+практика+java

Следите за выходом новых статей этой серии.

Этот контент является частью серии:Теория и практика Java

Следите за выходом новых статей этой серии.

Для большинства библиотек Java-класса Javadoc является единственной документацией. И за исключением компонентов коммерческого программного обеспечения, многие Java-классы не имеют Javadoc, стоящей упоминания. Хотя Javadoc исключительно хороша в качестве справочного инструмента API, она совсем не подходит для изучения того, как организован класс библиотеки и как он должен использоваться. И даже при наличии Javadoc, она часто содержит только самую основную информацию о том, что делает метод, не обращая внимания на такие важные характеристики, как обработка ошибок, домен и множество величин параметров и возвращаемых значений, безопасность потока, поведение блокировки, входные условия, выходные условия, инварианты или побочные эффекты.

Обучение от Javadoc

Для многих Java-функций, включая большинство пакетов с открытым исходным кодом и внутренних компонентов от производителей, реальность такова, что очень мало библиотек классов или компонентов поступают вместе со сколько-нибудь стоящей документацией, кроме Javadoc. Это значит, что разработчикам надо будет научиться использовать функции из Javadoc, и мы также должны принять это во внимание, организуя нашу Javadoc. Я часто шутил, что одним из наиболее важных умений для Java-программиста сегодня является квалифицированное использование Google и Javadoc для обратного проектирования плохо задокументированных API. Возможно, это и не далеко от истины, но совсем не весело.

Большинство Java-пакетов имеют какой-либо «корневой» объект, первый объект, который вам необходимо создать, прежде чем вы сможете добраться до любого другого объекта этой функции. В JNDI данный корневой объект — это Context, а в JMS и JDBC — это Connection. Если бы кто-нибудь сказал вам, что фундаментальный объект в JDBC — это Connection, и объяснил, как его получить, вы могли бы узнать из Javadoc, как затем создать и выполнить Statement и выполнить итерацию полученного ResultSet путем внимательного прочтения списка доступных методов в Javadoc. Но как узнать, что первым вашим действием было получение Connection? Javadoc организует классы в пакете и методы в классе в алфавитном порядке. К сожалению, не существует волшебного знака «Start Here (Начинать Здесь)» в Javadoc для привлечения читателей к логическому месту начала, с которого надо исследовать API.

Описание пакета

Наибольшим приближением к знаку «Start Here (Начинать Здесь)» является описание пакета, но оно редко когда используется эффективно. Если вы разместите файл package.html с исходным кодом для пакета, стандартный doclet положит содержимое в сгенерированный файл package-summary.html вместе с перечнем классов в данном пакете. К сожалению, стандартный doclet, выпускающий HTML документацию, которую мы все знаем, не позволяет легко найти описание пакета. Когда вы нажимаете на пакет в верхнем левом окне, то оно выдает список метода в нижнем левом окне, но не выводит резюме пакета в основном окне — вам придется нажать на имя пакета в нижнем левом окне, чтобы его увидеть. Но как бы там ни было, большинство пакетов не имеют описания.

Документация пакета является прекрасным местом для размещения документации «Start Here» в качестве обзора того, что пакет делает, каковы ключевые абстрактные конструкции, и с чего следует начинать изучать Javadoc-пакета.

Документация класса

Кроме документации пакета, документация классов также может значительно помочь пользователю перемещаться по новой функции. Документация классов должна, конечно же, включать описание того, что выполняет именно этот класс, но также и описание того, как этот класс соотносится с другими классами пакета, и в особенности идентифицировать любые значимые фабричные (factory) классы для данного класса. Например, документация для класса Statement в JDBC должна объяснять, что Statement получается с помощью метода createStatement() класса Connection. Таким образом, если новый пользователь имеет затруднения на странице Statement, он может узнать, что сначала ему необходимо получить Connection. Пакет, использующий это условное обозначение для каждого класса, быстро укажет пользователю на корневой объект, и пользователь сможет разобраться.

Поскольку Javadoc спроектирована для документирования конкретных классов, то зачастую в Javadoc не имеется явного места для размещения примерного кода, иллюстрирующего использование нескольких взаимосвязанных классов вместе. Но если фокусироваться на документации для конкретного класса или метода, мы не сможем поговорить о том, как пакет монтируется. Для многих пользователей было бы очень полезно, если бы имелся простой пример кода, демонстрирующий основное применение, или в документации пакета, или в документации класса для корневого объекта. Например, документация класса Connection могла бы иметь простой пример запроса соединения, создавая предварительное выражение, выполняя это выражение и итерируя полученный результат. Технически это может и не размещаться на странице Connection, поскольку также описываются и другие классы пакета. Тем не менее, особенно при соединении с вышеупомянутой технологией создания ссылок на классы, от которых зависит текущий класс, пользователь очень быстро найдет способ создать простой рабочий пример, независимо от организации класса.

Плохая документация == плохой код

Для большинства библиотек классов Java, за исключением коммерческих продуктов в составе пакета, Javadoc либо отсутствует, либо очень плохая. Принимая во внимание тот факт, что Javadoc является единственной имеющейся у нас документацией для большинства пакетов, на практике это означает, что мы признаемся в том, что большую часть нашего кода не сможет использовать никто, кроме самих его создателей — во всяком случае, не приложив значительных изыскательских усилий.

Поскольку документация теперь является частью кода, я думаю, что пора сообществу инженеров программного обеспечения согласиться с тем, что хороший код при плохой документации должен считаться плохим, потому что его будет невозможно эффективно повторно использовать. Так же как тестирование элементов, которое до недавнего времени имело плохую репутацию, и только недавно приобрело популярность у многих инженеров, API-документация должна также стать неотъемлемой частью процесса разработки для того, чтобы улучшить надежность производимого нами программного обеспечения и возможность его повторного использования.

Написание Javadoc является формой просмотра кода

Побочным эффектом создания приемлемой Javadoc является то, что нам приходится осуществить просмотр кодов, исследующих архитектуру наших классов и того, как они соотносятся друг с другом. Если пакет, класс или метод трудно задокументировать, возможно, программа пытается за один раз выполнить несколько задач и необходимо изменение ее конструкции.

Возможности самопромотра документации говорят об особой важности написания Javadoc на раннем этапе процесса разработки, а затем ее периодического обзора по мере развития кода, вместо того, чтобы просто дожидаться завершения кода, и только затем писать документацию (если на это останется время). При такой стратегии, которая весьма распространена, написание документации откладывается до финальной стадии проекта, когда графики поджимают, и сотрудники перегружены работой. И в результате мы слишком часто получаем бесполезную документацию, показанную в Листинге 1, которая создает лишь «иллюзию документации.» В ней не сообщается ничего действительно необходимого пользователю, никаких сведений о том, как работает данный класс.

Листинг 1. Типичная бесполезная Javadoc

    /**
      * Represents a command history
      */
    public class CommandHistory {

        /**
         * Get the command history for a given user
         */
        public static CommandHistory getCommandHistory(String user) {
        . . .
        }
    }

Из чего же должна состоять хорошая документация?

Описанные выше организационные технологии — снабжение соответствующими ссылками или фабричными классами в описании класса, включая обзор пакета и примеры кода — служат прекрасным началом для хорошей документации. Это помогает новым пользователям использовать Javadoc для ознакомления с новой функцией.

Но просмотр архитектуры — это только полдела. Другая половина — это практическое подробное объяснение того, что делают и чего не делают методы, при каких условиях они работают, и как они справляются с ошибками. Большинство Javadoc, даже тех, которые соответствующим образом описывают поведение метода в конкретном случае, не могут предоставить всей необходимой информации, включая:

• Как метод справляется с ситуациями ошибки или неверными вводами
• Как вызывающий оператор оповещается о ситуациях ошибки
• Какие конкретные подклассы исключений могут быть сгененрированы
• Какие значения подходят для вводов
• Инварианты класса, входные или выходные условия метода
• Побочные эффекты
• Существуют ли важные сцепления между методами
• Как класс работает с экземпляром, к которому одновременно обращаются множественные потоки

Правила Javadoc предоставляют тег @param, позволяющий нам задокументировать то, что означает параметр, в дополнение к его имени и типу. Тем не менее, не все методы соглашаются принять любое значение параметра. Например, в случае, когда допустимо передать нулевое значение (null) любому методу, принимающему параметр объекта без нарушения правил контроля типа, не все методы мягко соглашаются принять нулевое значение. В Javadoc должен быть ясно описан допустимый диапазон значений для параметров; если ожидается, что параметр будет не нулевым, то это должно быть указано, и если ожидаемые значения определенной области, такие как строки определенной длины или целые числа больше ноля, то это тоже должно быть указано. Не все методы тщательно проверяют свои параметры на предмет соответствия; отсутствие проверок соответствия и документации по множеству допустимых вводов запросто могут привести вас к аварийной ситуации.

Коды возврата

Javadoc позволяет легко описать возвращаемое значение, но, как и с параметрами метода, тег @return должен включать подробное описание множества значений, которые могут быть возвращены. Для типов возврата значения объекта будет ли когда-либо выдаваться ноль? Для типов возврата значения целого числа ограничивается ли результат набором известных или неотрицательных значений? Имеют ли какие-либо коды возврата особое значение, как, например, возврат -1 из java.io.InputStream.read() для обозначения конца файла? Используется ли код возврата для обозначения ситуации ошибки, как, например, возврат ноля в случае, если запись в таблице не может быть найдена?

Исключения

Стандартный doclet дублирует конструкцию throws метода, но Javadoc-теги @throws должны быть гораздо более конкретными. Например, NoSuchFileException является подклассом IOException, но большинство методов в java.io декларируются только для выброса IOException. Тем не менее, знание того, что метод может выбросить NoSuchFileException отдельно от других IOException является полезным для вызывающего — и этот метод должен быть включен в Javadoc. Также вы должны указать фактическую ситуацию ошибки, при которой будут выбрасываться различные классы исключений так, чтобы вызывающий знал, какое корректировочное действие предпринять в случае выброса данного исключения. Вы должны задокументировать каждое отмеченное и неотмеченное исключение, которое может выбросить метод, с помощью тега @throws, и задокументировать условия, при которых это исключение будет выброшено.

Входные условия, выходные условия и инварианты

Конечно, вы должны задокументировать влияние метода на состояние объекта. Но вы можете захотеть пойти дальше и описать входные условия метода, выходные условия и инварианты класса. Входное условие (precondition) является ограничением состояния объекта до вызова метода; например, входным условием вызова Iterator.next() является истинность hasMore(). Выходным условием (postcondition) является ограничение состояния объекта после завершения вызова метода, так List не является пустым после вызова add(). Инвариантом является ограничение состояния объекта, которое всегда действует постоянно, как Collection.size() == Collection.toArray().length().

Инструменты Design-by-contract, такие как jContract, позволяют вам указывать входные условия, выходные условия и инварианты класса, используя специальные комментарии, а затем инструменты генерируют дополнительный код для применения данных ограничений. Используете вы инструмент или нет для обеспечения данных вероятностей, документирование этих ограничений дает пользователям представление о том, что они могут безопасно сделать с классом.

Побочные эффекты

Иногда метод дает побочные эффекты, отличные от изменений состояния объекта, такие как изменения состояния взаимосвязанных объектов, JVM или базовой компьютерной платформы. Например, все методы, выполняющие I/O, имеют побочные эффекты. Некоторые побочные эффекты вполне безвредны, например, хранение сведений о количестве запросов, обработанных классом. Другие имеют значительное влияние на производительность и точность программы, как например модифицирование состояния объекта, передаваемого методу, или хранение копии ссылки на этот объект. Такие побочные эффекты как модифицирование состояния взаимосвязанных объектов или хранение ссылок на объекты, переданные как параметры метода, должны быть задокументированы.

Связывание (linkage) метода

Связывание метода означает, что два метода в классе опираются друг на друга и определяют поведение друг друга. Типичной ситуацией, когда это происходит, является тот случай, когда метод внутренне использует метод toString того же класса, и предполагает, что toString особым образом задаст формат состояния объекта. Данная ситуация может вызвать проблемы, если класс имеет подклассы, а метод toString отменен; другой метод внезапно прекратит корректное функционирование, если он сам не отменен (overridden). Если ваши методы опираются на способы реализации других методов, то необходимо задокументировать эти зависимости. Затем, если класс имеет подклассы, оба метода могут быть отменены соответствующим образом так, что подкласс все еще будет функционировать должным образом.

Безопасность потока

Одно из наиболее важных способов поведения, который вы должны задокументировать — и чего почти никогда не бывает — это безопасность потока. Является ли этот класс поточно-безопасным? Если нет, можно ли сделать его поточно-безопасным, упаковывая вызовы при помощи синхронизации? Должны ли эти синхронизации быть взаимосвязаны с конкретной программой-монитором, или подойдет любой монитор, использующийся согласованно? Вызывают ли методы блокировки объектов, видимых извне класса?

Безопасность потока в действительности не есть что-то бинарное; имеются несколько распознаваемых степеней безопасности потока. Задокументировать безопасность потока, или даже определить степень безопасности потока, не всегда легко. Но невозможность сделать это может привести к серьезным проблемам; использование поточно-небезопасных классов в текущих приложениях может вызвать спорадические неисправности, которые часто не проявляются до ввода в действие (когда приложение подвергается нагрузке). А надстройка дополнительной блокировки вокруг уже поточно-безопасных классов может повредить производительности и даже может вызвать взаимоблокировку.

В своей книге, Справочник по эффективному программированию на языке Java (см. Ресурсы) Джош Блох предлагает полезную таксономию для документирования степеней безопасности потока класса. Классы могут быть классифицированы по следующим группам, в порядке снижения безопасности потока: неизменяемые, поточно-безопасные, условно поточно-безопасные, поточно-совместимые, и поточно-неблагоприятные.

Данная классификация является отличной средой для сообщения существенной информации о поведении класса в случае параллельного доступа. Не имеет значения, используете ли вы именно эту таксономию или нет, но вы безусловно должны идентифицировать степень безопасности потока, на которую рассчитан ваш класс. Я бы также предложил, что если метод вызывает блокировку объекта, видимого извне кода класса, следует это задокументировать, даже если это только «деталь реализации,» для того, чтобы содействовать принятию решений о порядке глобальной блокировки и предотвращению взаимоблокировки.

Выводы

Документирование поведения класса это не просто краткое описание того, что делает каждый метод. Эффективная Javadoc должна содержать описания того:

• Как классы взаимосвязаны друг с другом
• Как методы влияют на состояние объекта
• Как методы сообщают вызывающим устройствам о ситуациях ошибки, и о каких ошибках они могут оповещать
• Как класс справляется с использованием в многопоточном приложении
• Домен аргументов метода и множество их возвращаемых значений

Плохая документация — или что еще хуже, ее отсутствие — может привести хороший код в состояние непригодности или одноразового пользования. Потратив немного дополнительного времени на документацию, вы сэкономите несчетное количество часов ваших пользователей (а может и своих).

Ресурсы для скачивания

Похожие темы

• Оригинал статьи: I have to document THAT?.
• В руководстве Sun «Как написать Doc Comments для инструмента Javadoc» описываются правила и философия Javadoc.
• Джош Блох (Josh Bloch) в Справочнике по эффективному программированию на языке Java делится множеством советов и методик по написанию лучшего кода.
• JContract является коммерческим инструментом для увеличения взаимодействия и ограничений классов .
• В статье «Особые методики» (JavaWorld, август 2001 г.) предлагаются рекомендации по написанию конструкций throws.
• Джереми Рошель (Jeremy Roschelle) в статье «Doclet your servlet» (JavaWorld, март 2001 г.) описывается то, как вы можете использовать пользовательские doclets для получения еще более подробной документации для сервлетов.
• Джон Фаррелл (John Farrell) рассуждает о важности Javadoc в рефакторинге Java-классов в «Сделайте плохой код хорошим» (JavaWorld, март, 2001).
• Скотт Амблер (Scott Ambler) предлагает удобную таблицу контрольных проверок для методов документирования (developerWorks, август 2000 г.).
• Интенсификатор документации для Java от IBM alphaWorks является инструментом, совершенствующим файлы Javadoc, путем дополнения их новой информацией (семантической информацией, сортировкой и управляемостью), которая собирается с помощью статического анализа соответствующих файлов Java-класса.
• Javadoc doclet API позволяет Вам написать пользовательские плагины Javadoc для получения различных видов документации, или даже автогенерирующего кода или схемы по комментариям Javadoc.
• Прочтите всю серию Теория и практика Java.
• Сотни ресурсов по Java-технологии в разделе Java-технологии developerWorks.

Подпишите меня на уведомления к комментариям

www.ibm.com

Документирование кода java, создание документации с помощью утилиты javadoc

/** Класс служит для хранения объектов-фруктов со свойствами

<b>name</b> и <b>color</b>

@author vitaly

@version 1.0

*/

public class Fruits {

    /** Свойство — цвет */

    String color;

    /** Свойство — имя */

    String name;

    /** Создает новый объект

     @see Fruits#Fruits(String)

     @see Fruits#Fruits(String, String)

     */

    public Fruits() {

 

    }

    /** Создает новый объект

     @param name Имя фрукта

     @see Fruits#Fruits()

     @see Fruits#Fruits(String, String)

     */

    public Fruits(String name) {

        this.name = name;

    }

    /** Создает новый объект

     @param name Имя фрукта

     @param color Цвет фрукта

     @see Fruits#Fruits()

     @see Fruits#Fruits(String)

     */

    public Fruits(String name, String color) {

        this.name = name;

        this.color = color;

    }

    /** Задает значение свойства name, которое можно получить при помощи метода {@link #getName()}

     @param name Новое значение свойства name

     */

    public void setName(String name) {

        this.name = name;

    }

    /** Получает значение свойства name, которое можно задать с помощью метода {@link #setName(String)}

     @return Значение свойства name

     */

    public String getName() {

        return name;

    }

    /** Задает значение свойства color, которое можно получить при помощи метода {@link #getColor()}

     @param color Новое значение свойства color

     */

    public void setColor(String color) {

        this.color = color;

    }

    /** Получает значение свойства color, которое можно задать с помощью метода {@link #setColor(String)}

     @return Значение свойства color

     */

    public String getColor() {

        return color;

    }

    /** Главный метод программы. Создает 3 объекта: apple, orange и lemon и устанавливает для них значения свойств, а затем выводит на экран

     @params args Параметры командной строки

     */

    public static void main(String[] args) {

        Fruits apple = new Fruits();

        apple.setName(«Apple»);

        apple.setColor(«Red»);

 

        Fruits orange = new Fruits(«Orange»);

        orange.setColor(«Orange»);

 

        Fruits lemon = new Fruits(«Lemon», «Yellow»);

 

        System.out.println(«Значение объекта apple:\nname = » + apple.name + «\ncolor = » + apple.color + «\n»);

        System.out.println(«Значение объекта orange:\nname = » + orange.name + «\ncolor = » + orange.color + «\n»);

        System.out.println(«Значение объекта lemon:\nname = » + lemon.name + «\ncolor = » + lemon.color + «\n»);

    }

}

www.fandroid.info

java — Используете ли вы Javadoc для каждого метода, который вы пишете?

@Claudiu

Когда я пишу код, который другие будут использовать — Да. Каждый метод, который может использовать кто-то другой (любой общедоступный метод), должен иметь javadoc, по крайней мере, указывая на его очевидную цель.

@Даниэль Спивак

Я тщательно документирую каждый публичный метод в каждом классе API. Классы, которые имеют публичные элементы, но не предназначенные для внешнего потребления, заметно выделяются в классе javadoc. Я также документирую каждый защищенный метод в каждом классе API, хотя и в меньшей степени. Это говорит о том, что любой разработчик, который расширяет класс API, уже будет иметь справедливое представление о том, что происходит.

Наконец, я буду иногда документировать частные и пакетные частные методы для моей собственной выгоды. Любой метод или область, которые, как мне кажется, нуждаются в некотором объяснении в ее использовании, получат документацию, независимо от ее видимости.

@Paul de Vrieze

Для вещей, таких как тривиальные геттеры и сеттеры, поделитесь комментарием между ними и опишите цель свойства, а не геттера/сеттера

/** 
 * Get the current value of the foo property.
 * The foo property controls the initial guess used by the bla algorithm in
 * {@link #bla}
 * @return The initial guess used by {@link #bla}
 */
int getFoo() {
  return foo;
}

И да, это больше работы.

@VonC

Когда вы нарушаете огромный комплексный метод (из-за причины высокой цикломатической сложности):

• один публичный метод, вызывающий
• несколько частных методов, которые представляют собой внутренние шаги публичного

очень полезно также javadoc для частных методов, хотя эта документация не будет видна в файлах javadoc API.
Тем не менее, это позволяет вам легче запомнить точный характер различных шагов вашего сложного алгоритма.

И помните: предельные значения или граничные условия должны быть частью вашего javadoc.

Плюс, javadoc лучше, чем просто «//комментарий» :

• Он распознается IDE и используется для отображения всплывающего окна при перемещении курсора поверх одной из ваших javadoc-ed-функций. Например, константа — частная статическая конечная переменная — должна иметь javadoc, особенно когда ее значение не является тривиальным. Пример: regexp (его javadoc должен содержать регулярное выражение в своей неэкранированной форме, то, что является целью, и литерал, сопоставляемый регулярным выражением)
• Его можно проанализировать с помощью внешних инструментов (например, xdoclet)

@Domci

Для меня, если кто-то увидит это или нет, это не имеет значения — вряд ли я буду знать, что некоторые неясные фрагменты кода, которые я написал, делают через пару месяцев. […]
Короче говоря, логика комментариев, а не синтаксис, и делайте это только один раз, в нужном месте.

@Мигель Пинг

Чтобы что-то прокомментировать, вы должны понять это в первую очередь. Когда вы пытаетесь прокомментировать функцию, вы на самом деле думаете о том, что делает метод/функция/класс, и это делает вас более конкретным и ясным в вашем javadoc, что, в свою очередь, заставляет вас писать более четкий и сжатый код, что хорошо.

qaru.site