วิธีแก้ปัญหา Java 8 Javadoc ที่เข้มงวดขึ้นเมื่อใช้ Maven

Question 1

คุณจะรู้ได้อย่างรวดเร็วว่า JDK8 นั้นเข้มงวดกว่ามาก (โดยค่าเริ่มต้น) เมื่อพูดถึง Javadoc ( ลิงค์ - ดูหัวข้อย่อยสุดท้าย)

หากคุณไม่เคยสร้าง Javadoc ใด ๆ เลยแน่นอนว่าคุณจะไม่ประสบปัญหาใด ๆ แต่สิ่งต่างๆเช่นกระบวนการเผยแพร่ Maven และการสร้าง CI ของคุณอาจล้มเหลวในทันทีที่พวกเขาทำงานได้ดีกับ JDK7 ทุกสิ่งที่ตรวจสอบค่าออกของเครื่องมือ Javadoc จะล้มเหลวในขณะนี้ JDK8 Javadoc น่าจะเป็น verbose มากกว่า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 เอาชนะฉัน ??

สิ่งที่ล้มเหลวในตอนนี้ด้วยเหตุผลที่ชัดเจนมากขึ้น

ลิงก์ไม่ถูกต้องเช่น {@link notexist}
HTML ผิดรูปแบบเช่น always returns <code>true<code> if ...

อัปเดต

ลิงค์:

ยอดเยี่ยมบล็อกเกี่ยวกับเรื่องนี้โดยสตีเฟ่น Colebourne

Question 2

สำหรับตอนนี้วิธีที่ง่ายที่สุดที่ฉันรู้ในการจัดการกับ 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!

Question 3

หากคุณใช้ปลั๊กอิน 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>

สำหรับข้อมูลเพิ่มเติมข้อมูล

Question 4

ตั้งแต่เวอร์ชัน 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>

Question 5

ฉันชอบวิธีแก้ปัญหาของ @ ThiagoPorciúncula แต่มันก็ไม่ได้ไปไกลพอสำหรับฉัน

โดยทั่วไปฉันมีadditionalparamชุดปลั๊กอิน javadoc ซึ่งโปรไฟล์ไม่ได้ถูกแทนที่ ด้วยเหตุนี้ฉันจึงต้อง:

ตั้งค่าdisableDoclintคุณสมบัติเป็นค่าเริ่มต้น
ถ้าใน java> = 8 ให้ตั้งค่าdisableDoclintคุณสมบัติเป็น-Xdoclint:none
ใช้${disableDoclint} in theadditionalparam 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 Woo hoo!

Question 6

โปรดทราบว่าสำหรับข้อผิดพลาดการno summary or caption for tableใช้<table summary="">จะไม่ทำงานอีกต่อไป หากเป็นสถานการณ์ของคุณให้เพิ่ม<caption>องค์ประกอบลงในตารางของคุณดังนี้:

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

หวังว่านี่จะช่วยใครบางคนได้ ฉันใช้เวลาสักพักจนกว่าฉันจะพบสิ่งนี้