it-swarm.com.ru

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

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

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

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

Обновление

Ссылки:

Отлично блог на эту тему от Стивен Colebourne .

126
peterh

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

53
Fred Porciúncula

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

Для более информация .

50
assylias

Начиная с версии 3.0.0 maven-javadoc-plugin, документация настраивается через специальный тег XML

<plugin>
    <groupId>org.Apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <version>3.0.0</version>
    <configuration>
       <doclint>none</doclint>
    </configuration>
</plugin>
3
Vlad Isajkin

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

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

  • Установите свойство disableDoclint по умолчанию пустым.
  • Если в Java> = 8, установите для свойства disableDoclint значение -Xdoclint:none
  • Использование ${disableDoclint} in theadditionalparamsection 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. Woo hoo!

3
Gray

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

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

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

0
Jeronimo Backes