Javadoc как пользоваться – Документирование кода javadoc

Урок 20. Javadoc — Java Core

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

Javadoc — генератор документации в HTML-формате из комментариев исходного кода на Java. 

Комментарии документации применяют для документирования:

• классов,
• интерфейсов,
• полей (переменных),
• конструкторов,
• методов,
• пакетов.

В каждом случае комментарий должен находиться перед документируемым элементом.

Утилита javadoc

позволяет вставлять HTML тэги и использовать специальные ярлыки (дескрипторы) документирования.

НТМL тэги заголовков не используют, чтобы не нарушать стиль файла, сформированного утилитой.

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

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

Дескриптор	Описание	Применим к
@author	Автор	класс, интерфейс
@version	Версия. Не более одного дескриптора на класс.	класс, интерфейс
@since	Указывает, с какой версии доступно.	класс, интерфейс, поле, метод
@see	Ссылка на другое место в документации.	класс, интерфейс, поле, метод
@param	Входной параметр метода.	метод
@return	Описание возвращаемого значения.	метод
@deprecated	Описание устаревших блоков кода.	класс, интерфейс, поле, метод
{@link reference}	Ссылка.	класс, интерфейс, поле, метод
{@value}	Описание значения переменной.	статичное поле

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

Ctrl+Q – просмотр документации.

 

Generate JavaDoc Dialog

www.examclouds.com

documentation Как вы читаете JavaDoc?

java documentation javadoc

Какие инструменты / веб-сайты вы используете для чтения JavaDocs?

В настоящее время я использую Firefox с 20 + вкладками, открытыми при работе над проектом J2EE, чтобы иметь всю доступную документацию, которая не очень удобна в использовании, слишком много памяти и не поддается поиску.

Что я ожидаю от такого инструмента / веб-сайта:

• Совокупные JavaDocs из разных мест
• Прямой доступ к таким типам, как Ctrl + T в Eclipse или подобный
• Полнотекстовый поиск
• Перекрестные ссылки между всеми выбранными мной библиотеками Java
• Для инструмента: автономная поддержка
• скорость

не обязательно:

• возможность комментировать вещи
• поддержка разных версий библиотеки (+ diffing?)
• Интеграция IDE

Редактировать:

Спасибо за ваши ответы. Я знал большинство сайтов, но дал им еще одну попытку. Вот мое суждение:

• встроенные функции Eclipse / IDE
  • тесно интегрированный
  • автономная / онлайн-поддержка
• javadoconline.com (больше не поддерживается)
  • работает
  • чистый внешний вид
  • находит совпадения в более чем одной версии api и позволяет легко переключаться
  • простой, но рабочий
  • быстро
• jdocs (offline)
  • кажется очень сложным
  • иногда медленно
  • некоторые недавние версии библиотек, кажется, отсутствуют (Seam 2.0.0, Hibernate Validators), но похоже, что вы можете их добавлять самостоятельно
  • Интеграция IDE (не проверена)
  • комментарии в стиле вики к каждому элементу
• docjar.com
  • работает
  • быстро
  • загроможденный пользовательский интерфейс
• javadoc_isearch
  • скрипт greasemonkey для firefox, который упрощает навигацию по javadocs
  • работает гладко и отлично

code-examples.net

java — Как работать с более строгим Java 8 Javadoc при использовании Maven

Вы быстро поймете, что JDK8 намного строже (по умолчанию), когда дело доходит до Javadoc. (ссылка — см. последнюю маркерную точку)

Если вы никогда не генерируете Javadoc, то, конечно, у вас не возникнут какие-либо проблемы, но такие вещи, как процесс выпуска Maven и, возможно, ваши сборки CI неожиданно потерпят неудачу, когда они отлично работают с JDK7. Все, что проверяет значение выхода инструмента Javadoc, теперь терпит неудачу. JDK8 Javadoc, вероятно, также является более подробным в терминах warnings по сравнению с JDK7, но это не область действия здесь. Мы говорим о errors!

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

Вы также можете прокомментировать истории о том, что теперь не удается, что прошло бы раньше.

Истории ужасов о том, что сейчас терпит неудачу

инструменты wsimport

Инструмент

wsimport — это генератор кода для создания веб-сервисов. Он включен в JDK. Даже если вы используете инструмент wsimport из JDK8, он все равно будет генерировать исходный код который не может быть скомпилирован с помощью javadoc-компилятора из JDK8.

тег @author

Я открываю файлы исходного кода 3-4 года и вижу это:

/**
 * My very best class
 * @author John <[email protected]> 
 */

Теперь это не удается из-за < персонаж. Строго говоря, это оправдано, но не очень прощает.

Таблицы HTML

Таблицы HTML в вашем Javadoc? Рассмотрим этот допустимый HTML:

/**
 *
 * <table>
 *   <tr>
 *      <td>Col1</td><td>Col2</td><td>Col3</td>
 *   </tr>
 * </table>
 */
 

Теперь это сообщение об ошибке с сообщением об ошибке no summary or caption for table. Одно быстрое решение состоит в следующем:

/**
 *
 * <table summary="">
 *   <tr>
 *      <td>Col1</td><td>Col2</td><td>Col3</td>
 *   </tr>
 * </table>
 */

но почему это должно быть ошибкой Stop-the-world от инструмента Javadoc, меня бьет?

Вещи, которые теперь терпят неудачу по более очевидным причинам

• Неверные ссылки, например. {@link notexist}
• Отформатированный HTML-код, например. always returns <code>true<code> if ...

UPDATE

Ссылки:

Отличный блог по теме Стивен Коулборн.

qaru.site

java — /** и /* в Java Комментарии

Чтение раздела 3.7 JLS хорошо объясняет все, что вам нужно знать о комментариях в Java.

Есть два вида комментариев:

Традиционный комментарий: весь текст из символов ASCII/* на символы ASCII */игнорируется (как в C и С++).

Комментарий конца строки: весь текст из символов ASCII//в конец строки игнорируется (как в С++).

---

О вашем вопросе

Первый

/**
 *
 */

используется для объявления технологии Javadoc.

Javadoc — это инструмент, который анализирует декларации и документацию комментарии в наборе исходных файлов и создает набор HTML-страниц описывая классы, интерфейсы, конструкторы, методы и поля. Вы можете использовать Javadoc doclet для настройки вывода Javadoc. Доклет программа, написанная с помощью API Doclet, который определяет контент и формат вывода, который должен быть сгенерирован инструментом. Вы можете написать doclet для генерации любых выходных текстовых файлов, таких как HTML, SGML, XML, RTF и MIF. Oracle предоставляет стандартный документ для генерации Документация HTML-формата. Доклеты могут также использоваться для выполнения специальные задачи, не связанные с созданием документации API.

Для получения дополнительной информации о Doclet обратитесь к API.

Второй, как объясняется в JLS, будет игнорировать весь текст между /* и */, поэтому используется для создания многострочных комментариев.

---

Некоторые другие вещи, которые вы, возможно, захотите узнать о комментариях в Java

• Комментарии не вложены.
• /* and */ не имеют особого значения в комментариях, начинающихся с //.
• // не имеет особого значения в комментариях, начинающихся с /* or /**.
• Лексическая грамматика подразумевает, что комментарии не встречаются в символьных литералах (§3.10.4) или строковых литералах (§3.10.5).

Таким образом, следующий текст представляет собой один полный комментарий:

/* this comment /* // /** ends here: */

qaru.site

java — Как ссылаться на javadocs на зависимости в плагине Maven eclipse, когда javadoc не привязан к зависимости

Обычно Javadocs не используются в основном как зависимость. Потому что они не требуются при компиляции или во время выполнения. Это просто, чтобы помочь разработчику при разработке или отладке.

Предполагая, что с помощью java IDE Eclipse мы можем использовать java-документы в качестве ссылок. Ниже приведены подходы, которые мы можем связать javadocs/sources с соответствующими банками.

1. Если его немощный проект:

Загрузите javadocs jar или zipped файл, независимо от того, что доступно, и поместите его в какой-либо каталог. Щелкните правой кнопкой мыши проект приложения в Eclipse IDE, выберите «Свойства» и выберите «Путь сборки Java», затем выберите вкладку «Библиотеки» в разделе «Путь сборки Java». Теперь разверните банку, которую вы хотите связать с java docs/source. Выберите ссылку на местоположение Javadoc и нажмите кнопку «Изменить», появится новое окно, где нам нужно выбрать путь javadocs jar. Нажмите «ОК», и мы связали javadoc/source с соответствующими банками.

2. Если его проект maven

Если мы используем проект Maven, перейдите в jar файлы под зависимостью Maven в проекте в представлении Project Explorer, как показано ниже. Теперь щелкните правой кнопкой мыши на файле jar, который вы хотите добавить в Javadoc/source,  выберите Maven, затем щелкните Javadoc или Source, который вы хотите связать с проектом. Теперь IDE автоматически загрузит требуемый javadoc/source и свяжет его с соответствующим банком в проекте.

Вы можете проверить это, щелкнув правой кнопкой мыши по проекту в среде IDE и выбрав «Путь сборки Java» и выбрав вкладку «Библиотеки» в разделе «Путь сборки Java», а затем разверните нужную банку, здесь, когда вы нажмете кнопку «Изменить», вы увидите связанный путь Javadoc/Source с соответствующей банкой, как показано ниже на изображении.

3. Если его проект Maven и мы устанавливаем поведение по умолчанию:

Eclipse будет активно загружать javadoc/source вместе с основным необходимым банком при запуске. По умолчанию задание инструкции Maven для загрузки Javadoc/источников для всех банок, связанных в проекте.

Нажмите Windows — настройки — выберите Maven и установите флажок Загрузить Artifact Javadoc, как показано ниже

Теперь нажмите «Применить» и сохранить его, и теперь, когда вы создаете новый проект Maven, по умолчанию Javadocs будет загружен и связан со всеми зависимыми баночками в проекте.
Вы можете проверить, щелкнув правой кнопкой мыши по проекту, а свойства и в пути Java Build можно увидеть, что javadocs связаны со всеми банками, как показано ниже.

Если ваш проект — проект Maven, то его всегда лучше использовать 2-й подход, потому что, используя этот подход, IDE и Maven, заботятся о загрузке правильной версии Javadoc/source и связывают ее с соответствующим банком как хорошо.

Подход 3 — это дорого стоить, потому что javadoc/sources будут загружены для всех зависимых банок, возможно, вас не интересуют javadocs/sources для всех зависимых банок.

qaru.site