Como solucionar o Javadoc Java 8 mais rigoroso ao usar o Maven

Você perceberá rapidamente que o JDK8 é muito mais rigoroso (por padrão) quando se trata de Javadoc. ( link - veja o último ponto)

Se você nunca gerar nenhum Javadoc, é claro que não terá problemas, mas coisas como o processo de liberação do Maven e, possivelmente, as compilações de seus ICs falharão repentinamente onde eles funcionaram muito bem com o JDK7. Qualquer coisa que verifique o valor de saída da ferramenta Javadoc agora falhará. JDK8 Javadoc provavelmente também é mais detalhado em termos de warningsJDK7, mas esse não é o escopo aqui. Estamos a falar errors!

Esta pergunta existe para coletar propostas sobre o que fazer sobre isso. Qual é a melhor abordagem ? Esses erros devem ser corrigidos de uma vez por todas nos arquivos de código-fonte? Se você tem uma enorme base de código, pode ser muito trabalhoso. Que outras opções existem?

Você também pode comentar com histórias do que agora falha e que passaria anteriormente.

Histórias de horror do que agora falha

ferramentas wsimport

wsimportA ferramenta é um gerador de código para criar consumidores de serviços da web. Está incluído no JDK. Mesmo se você usar a wsimportferramenta do JDK8, ela produzirá código fonte que não pode ser compilado com o compilador javadoc do JDK8 .

@author tag

Estou abrindo arquivos de código fonte de 3 a 4 anos e veja o seguinte:

/**
 * My very best class
 * @author John <[email protected]> 
 */

Isso agora falha devido ao caractere <. A rigor, isso é justificado, mas não muito perdoador.

Tabelas HTML

Tabelas HTML no seu Javadoc? Considere este HTML válido:

/**
 *
 * <table>
 *   <tr>
 *      <td>Col1</td><td>Col2</td><td>Col3</td>
 *   </tr>
 * </table>
 */

Isso agora falha com a mensagem de erro no summary or caption for table. Uma solução rápida é fazer assim:

/**
 *
 * <table summary="">
 *   <tr>
 *      <td>Col1</td><td>Col2</td><td>Col3</td>
 *   </tr>
 * </table>
 */

mas por que isso tem que ser um erro de parar o mundo da ferramenta Javadoc me bate?

Coisas que agora falham por razões mais óbvias

1. Links inválidos, por exemplo {@link notexist}
2. HTML malformado, por exemplo always returns <code>true<code> if ...

ATUALIZAR

Ligações:

Excelente blog sobre o assunto, de Stephen Colebourne .

Por enquanto, a maneira mais fácil de solucionar o Javadoc Java 8 mais rigoroso ao usar o Maven é desativá-lo.

Como o parâmetro -Xdoclint:noneexiste apenas no Java 8, a definição desse parâmetro interrompe a construção de qualquer outro Java. Para evitar isso, podemos criar um perfil que estará ativo apenas para o Java 8, certificando-se de que nossa solução funcione independentemente da versão do Java.

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

Basta adicionar isso ao seu POM e você estará pronto.

Para usuários do maven-javadoc-plugin 3.0.0:

Substituir

<additionalparam>-Xdoclint:none</additionalparam>

de

<doclint>none</doclint>

Obrigado @banterCZ!

Se você estiver usando o plugin maven javadoc, poderá usar a failOnErroropção para impedir que ele pare se encontrar algum erro de html:

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

Ou você pode desativar completamente as rigorosas opções de html com:

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

Para mais informações .

Desde a versão 3.0.0 do maven-javadoc-plugin, o doclint é configurado através da tag XML dedicada

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

Gosto da solução do @ ThiagoPorciúncula, mas não foi o suficiente para mim.

Normalmente, eu já tenho o additionalparamconjunto de plug-ins javadoc que não estavam sendo substituídos pelo perfil. Por causa disso, tive que:

• Defina uma disableDoclintpropriedade para estar vazia por padrão.
• Se em java> = 8, configure a disableDoclintpropriedade como-Xdoclint:none
• O uso ${disableDoclint} in theadicionalparam section of themaven-javadoc-plugin`.

Isso parece funcionar bem, embora detalhado.

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

Abaixo, eu poderia usar a ${disableDoclint}variável opcional na additionalparamseção que eu já havia definido.

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

Isso funciona no java 8, mas não causa erros de sintaxe no java 7. Woo hoo!

Observe que, para o erro no summary or caption for table, o uso <table summary="">não funcionará mais. Se essa for a sua situação, adicione um <caption>elemento à sua tabela, assim:

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

Espero que isto seja útil a alguém. Levei um tempo até eu descobrir isso.