Maven'i kullanırken daha katı Java 8 Javadoc'u aşma

Konu Javadoc olduğunda JDK8'in çok daha katı (varsayılan olarak) olduğunu çabucak anlayacaksınız. ( bağlantı - son madde işaretine bakın)

Asla herhangi bir Javadoc oluşturmazsanız, o zaman elbette herhangi bir sorun yaşamazsınız, ancak Maven sürüm süreci gibi şeyler ve muhtemelen CI yapılarınız, JDK7 ile gayet iyi çalıştıklarında aniden başarısız olur. Javadoc aracının çıkış değerini kontrol eden her şey artık başarısız olacaktır. JDK8 Javadoc, muhtemelen warningsJDK7'ye kıyasla daha ayrıntılıdır, ancak buradaki kapsam bu değildir. Biz bahsediyoruz errors!

Bu soru, bu konuda ne yapılacağına dair öneriler toplamak için var. En iyi yaklaşım nedir? Bu hatalar kaynak kod dosyalarında bir kez ve tümü için düzeltilmeli mi? Büyük bir kod tabanınız varsa, bu çok fazla iş olabilir. Başka hangi seçenekler var?

Ayrıca, daha önce geçecek olan şimdi başarısız olanların hikayelerini de paylaşabilirsiniz.

Şimdi başarısız olanların korku hikayeleri

wsimport araçları

wsimportaracı, web hizmeti tüketicileri oluşturmak için bir kod üretecidir. JDK'ya dahildir. Eğer kullansanız bile wsimportJDK8 gelen aracı yine de kaynak kodu üretecektir JDK8 gelen javadoc derleyici ile derlenmiş edilemez .

@author etiketi

3-4 yıllık kaynak kod dosyalarını açıyorum ve şunu görüyorum:

/**
 * My very best class
 * @author John <john.doe@mine.com> 
 */

Bu artık <karakteri nedeniyle başarısız oluyor. Açıkça söylemek gerekirse, bu haklı, ancak çok bağışlayıcı değil.

HTML tabloları

Javadoc'unuzdaki HTML Tabloları? Bu geçerli HTML'yi düşünün:

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

Bu artık hata mesajı ile başarısız olur no summary or caption for table. Hızlı bir çözüm şu şekilde yapmaktır:

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

ama neden bu Javadoc aracından gelen dünyayı durdurma hatası olmak zorunda?

Artık daha bariz nedenlerle başarısız olan şeyler

1. Geçersiz bağlantılar, ör. {@link notexist}
2. Yanlış biçimlendirilmiş HTML, ör. always returns <code>true<code> if ...

GÜNCELLEME

Bağlantılar:

Stephen Colebourne tarafından konuyla ilgili mükemmel bir blog .

Şimdilik, Maven'i kullanırken daha katı Java 8 Javadoc'u aşmanın bildiğim en kolay yolu onu devre dışı bırakmaktır.

Parametre -Xdoclint:noneyalnızca Java 8'de mevcut olduğundan, bu parametrenin tanımlanması, diğer Java'lar için yapıyı bozar. Bunu önlemek için, yalnızca Java 8 için etkin olacak bir profil oluşturabilir ve çözümümüzün Java sürümünden bağımsız olarak çalıştığından emin olabiliriz.

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

Sadece bunu POM'nuza ekleyin ve gitmeniz iyi olur.

Maven-javadoc-plugin 3.0.0 kullanıcıları için:

değiştirmek

<additionalparam>-Xdoclint:none</additionalparam>

tarafından

<doclint>none</doclint>

Teşekkürler @banterCZ!

Maven javadoc eklentisini kullanıyorsanız, failOnErrorherhangi bir html hatası bulursa , eklentinin durmasını önlemek için seçeneği kullanabilirsiniz :

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

Veya katı html seçeneklerini aşağıdakilerle tamamen devre dışı bırakabilirsiniz:

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

Daha fazla bilgi için .

Maven-javadoc-eklentisinin 3.0.0 sürümünden bu yana, doclint özel XML etiketi aracılığıyla yapılandırılır

<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'nın çözümünü beğendim ama benim için yeterince ileri gitmedi.

additionalparamProfil tarafından geçersiz kılınmayan javadoc eklenti setine zaten sahibim . Bu yüzden yapmak zorundaydım:

• Bir disableDoclintözelliği varsayılan olarak boş olacak şekilde ayarlayın .
• Java> = 8 ise, disableDoclintözelliği şöyle ayarlayın-Xdoclint:none
• Kullanım ${disableDoclint} in theadditionalparam section of themaven-javadoc-plugin`.

Bu ayrıntılı da olsa iyi çalışıyor gibi görünüyor.

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

Daha sonra aşağıda daha önce tanımlamış olduğum bölümde isteğe bağlı ${disableDoclint}değişkeni kullanabilirim 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>

Bu java 8 altında çalışır ama java 7 altında sözdizimi hatalarına neden olmaz. Woo hoo!

Hata için no summary or caption for tablekullanmanın <table summary="">artık çalışmayacağını unutmayın. Durumunuz buysa, <caption>tablonuza şunun gibi bir öğe ekleyin :

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

Umarım bu dışarıdaki birine yardımcı olur. Bunu öğrenene kadar biraz zamanımı aldı.