Як обійти більш жорстку Java 8 Javadoc при використанні Maven

Ви швидко зрозумієте, що JDK8 набагато суворіший (за замовчуванням), коли мова йде про Javadoc. ( посилання - див. останній пункт кулі)

Якщо ви ніколи не генеруєте жодного Javadoc, то, звичайно, у вас не виникне жодних проблем, але такі речі, як процес випуску Maven і, можливо, ваші збірки CI раптом вийдуть з ладу там, де вони добре працювали з JDK7. Все, що перевіряє значення виходу інструменту Javadoc, тепер не вдасться. JDK8 Javadoc, ймовірно, також є більш багатослівним в warningsпорівнянні з JDK7, але це не в цій галузі. Ми говоримо про errors!

Це питання існує для збору пропозицій щодо того, що з цим робити. Який найкращий підхід? Чи слід ці помилки виправляти раз у раз у файлах вихідного коду? Якщо у вас є величезна база коду, це може бути багато роботи. Які ще існують варіанти?

Ви також можете прокоментувати розповіді про те, що зараз не вдалося, що раніше пройшло.

Страшилки про те, що зараз не вдається

Інструменти для імпорту

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-плагіна, 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 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!

Зауважте, що для помилки no summary or caption for tableвикористання <table summary="">більше не працюватиме. Якщо це ваша ситуація, додайте <caption>до таблиці такий елемент, як ось такий:

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

Сподіваюся, це допомагає комусь там. Минуло деякий час, поки я не з'ясував це.