Решение проблемы Maven и Java 8 при неполных Javadoc тегах
Быстрый ответ
Если в Java 8 сборка Maven прерывается из-за ошибок Javadoc, настройте maven-javadoc-plugin
так, чтобы он не принимал во внимание ошибки. Добавьте в файл pom.xml
следующий фрагмент:
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<configuration>
<failOnError>false</failOnError>
</configuration>
</plugin>
Теперь Maven продолжит процесс сборки, даже в случае обнаружения ошибок в документации.
Стратегия работы с неполными тегами Javadoc в Java 8
Исправление ошибок Javadoc: Ключевой подход
Игнорирование ошибок – это лишь временное решение. Корректировка ошибок Javadoc в исходных кодах – важный аспект для создания качественной документации и предотвращения возможных недопониманий и ошибок в будущем.
Работа с DocLint в Java 8: Настроил и забыл
Java 8 представила DocLint для строгого контроля Javadoc. Чтобы отключить DocLint, в настройках maven-javadoc-plugin
используйте флаг -Xdoclint:none
:
<additionalparam>-Xdoclint:none</additionalparam>
Профилирование в Javadoc: В соответствии с требованиями JDK
Создайте профиль Maven, который будет активен только при сборке с использованием Java 8. Это позволит поддерживать совместимость с другими версиями Java:
<profiles>
<profile>
<id>doclint-java8-disable</id>
</profile>
</profiles>
Обеспечивайте совместимость с разными версиями JDK: Проверьте во всех средах
Проверяйте ваш код в разных версиях JDK, включая 6, 7, 8 и более новые. Для этого можно использовать инструменты непрерывной интеграции, обеспечивая совместимость вашей документации с разными версиями.
Mojo для различных сценариев в Maven
Поддержка пользователей Maven 3.0.0: Присоединяйтесь к сообществу!
Если вы используете Maven 3.0.0, замените <additionalparam>
на <doclint>
, так как конфигурация плагина может быть разной в зависимости от версии Maven.
Принцип DRY для управления плагином Javadoc: Давайте систематизировать!
Можно избежать хаоса в настройках, определив все нужные параметры в секции <properties>
. Пример настройки javadoc.opts
:
<properties>
<javadoc.opts>-Xdoclint:none</javadoc.opts>
</properties>
В maven-javadoc-plugin
ссылаемся на эти параметры следующим образом:
<additionalparam>${javadoc.opts}</additionalparam>
Будьте всеобъемлющими в настройках: Синергия подходов
Часто оптимальную конфигурацию можно достигнуть, сочетая разные подходы, адаптированные под каждый конкретный проект.
Визуализация
Значимость полных тегов Javadoc для Maven в Java 8 можно наглядно представить так:
Java 8
|
[🛠 Maven]
|
😥 Незавершенные теги Javadoc
|
🔴 Сборка не была завершена успешно
В отличие от:
Java 8
|
[🛠 Maven]
|
😃 Завершенные теги Javadoc
|
🟢 Сборка успешно завершена
Здесь Maven выступает в роли строгого контролера. Ошибки в Javadoc приводят к остановке процесса (красный свет), в то время как полностью оформленная документация гарантирует успешное завершение сборки (зеленый свет).
Полезные материалы
- Apache Maven Javadoc Plugin – Использование — руководство по использованию плагина Javadoc в Maven.
- Как писать комментарии Doc для инструмента Javadoc — документация Oracle о регламенте написания документации Javadoc.
- Отслеживание проблем Javadoc плагина Apache Maven — последние новости и известные проблемы Javadoc плагина Maven.
- Apache Maven Javadoc Plugin – Агрегирование Javadoc для многопроектов — методы объединения Javadoc в мульти-проектной среде Maven.