Как обойти более строгий 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 <john.doe@mine.com> 
 */

Теперь это не удается из-за символа <. Строго говоря, это оправдано, но не прощает ошибок.

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>
 */

но почему это должна быть ошибка остановки мира из инструмента Javadoc, меня бьет ??

То, что сейчас терпит неудачу по более очевидным причинам

1. Недействительные ссылки, например {@link notexist}
2. Неправильный HTML, например always returns <code>true<code> if ...

ОБНОВИТЬ

Ссылки:

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

На данный момент самый простой способ обойти более строгий 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, и все готово.

Для пользователей maven-javadoc-plugin 3.0.0:

замещать

<additionalparam>-Xdoclint:none</additionalparam>

по

<doclint>none</doclint>

Спасибо @banterCZ!

Если вы используете плагин 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>

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

Начиная с версии 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>

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

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

• Установите disableDoclintсвойство как пустое по умолчанию.
• Если в java> = 8, установите для disableDoclintсвойства значение-Xdoclint:none
• Использование ${disableDoclint} in theдополнительных параметров section of themaven-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. Ура!

Обратите внимание, что для ошибки no summary or caption for tableиспользование <table summary="">больше не работает. Если это ваша ситуация, добавьте <caption>элемент в свою таблицу, например:

<table>
    <caption>Examples</caption>
    ...
</table>

Надеюсь, это поможет кому-то там. Мне потребовалось время, прежде чем я узнал это.