Решение проблемы 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 приводят к остановке процесса (красный свет), в то время как полностью оформленная документация гарантирует успешное завершение сборки (зеленый свет).

Полезные материалы

1. Apache Maven Javadoc Plugin – Использование — руководство по использованию плагина Javadoc в Maven.
2. Как писать комментарии Doc для инструмента Javadoc — документация Oracle о регламенте написания документации Javadoc.
3. Отслеживание проблем Javadoc плагина Apache Maven — последние новости и известные проблемы Javadoc плагина Maven.
4. Apache Maven Javadoc Plugin – Агрегирование Javadoc для многопроектов — методы объединения Javadoc в мульти-проектной среде Maven.