Как работать с более строгим 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

Ссылки:

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

ОТВЕТЫ

Ответ 1

На данный момент самый простой способ, которым я знаю, работать с более строгим Java 8 Javadoc при использовании Maven, дезактивирует его.

Поскольку параметр -Xdoclint:none существует только в Java 8, определение этого параметра прерывает сборку для любой другой Java. Чтобы предотвратить это, мы можем создать профиль, который будет активен только для Java 8, убедившись, что наше решение работает независимо от версии Java.

<profiles>
    <profile>
        <id>disable-java8-doclint</id>
        <activation>
            <jdk>[1.8,)</jdk>
        </activation>
        <properties>
            <additionalparam>-Xdoclint:none</additionalparam>
        </properties>
    </profile>
</profiles>

Просто добавьте это в свой POM, и вы хорошо пойдете.

Ответ 2

Если вы используете плагин maven javadoc, вы можете использовать опцию failOnError, чтобы предотвратить ее остановку, если она обнаруживает любые ошибки HTML:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-javadoc-plugin</artifactId>
  <configuration>
    <failOnError>false</failOnError>
  </configuration>
</plugin>

Или вы можете полностью отключить строгие параметры html с помощью:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-javadoc-plugin</artifactId>
    <configuration>
      <additionalparam>-Xdoclint:none</additionalparam>
    </configuration>
  </plugin>
</plugins>

Подробнее info.

Ответ 3

Мне нравится решение @ThiagoPorciúncula, но для меня это не совсем ушло.

Обычно у меня уже есть набор javadoc plugin additionalparam, который не был переопределен профилем. Из-за этого мне пришлось:

  • По умолчанию свойство disableDoclint должно быть пустым.
  • Если в java >= 8, установите для свойства disableDoclint значение -Xdoclint:none
  • Использовать ${disableDoclint} in the дополнительныйпарам section of the maven-javadoc-plugin`.

Это, кажется, работает хорошо, хотя и многословно.

<properties>
    <!-- set empty property -->
    <disableDoclint></disableDoclint>
</properties>
<profiles>
    <profile>
        <id>disable-java8-doclint</id>
        <activation>
            <jdk>[1.8,)</jdk>
        </activation>
        <properties>
            <!-- set property if >= java 8 -->
            <disableDoclint>-Xdoclint:none</disableDoclint>
        </properties>
    </profile>
    ...
</profiles>

Затем ниже, я мог бы использовать необязательную переменную ${disableDoclint} в разделе additionalparam, который я уже определил.

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <executions>
        <execution>
            <goals>
                <goal>jar</goal>
            </goals>
            <configuration>
                <showPackage>false</showPackage>
                <additionalparam>-tag inheritDoc:X ${disableDoclint}</additionalparam>
            </configuration>
        </execution>
    </executions>
    <configuration>
        <showPackage>false</showPackage>
        <bottom>This documentation content is licensed...</bottom>
        <additionalparam>-tag inheritDoc:X ${disableDoclint}</additionalparam>
    </configuration>
</plugin>

Это работает под java 8, но не вызывает синтаксических ошибок в java 7. Woo hoo!

Ответ 4

Начиная с версии 3.0.0 maven-javadoc-plugin doclint настраивается через выделенный тег XML 

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>3.0.0</version>
    <configuration>
       <doclint>none</doclint>
    </configuration>
</plugin>