Cách làm việc xung quanh Java 8 Javadoc chặt chẽ hơn khi sử dụng Maven

Bạn sẽ nhanh chóng nhận ra rằng JDK8 nghiêm ngặt hơn rất nhiều (theo mặc định) khi nói đến Javadoc. ( liên kết - xem điểm đạn cuối cùng)

Nếu bạn không bao giờ tạo bất kỳ Javadoc nào thì tất nhiên bạn sẽ không gặp phải bất kỳ vấn đề nào, nhưng những thứ như quy trình phát hành Maven và có thể các bản dựng CI của bạn sẽ đột nhiên thất bại khi chúng hoạt động tốt với JDK7. Bất cứ điều gì kiểm tra giá trị thoát của công cụ Javadoc sẽ thất bại. JDK8 Javadoc có lẽ cũng dài dòng warningshơn so với JDK7 nhưng đó không phải là phạm vi ở đây. Chúng ta đang nói về errors!

Câu hỏi này tồn tại để thu thập các đề xuất về những gì cần làm về nó. Đâu là cách tiếp cận lí tưởng nhất ? Những lỗi này có nên được sửa một lần và cho tất cả trong các tệp mã nguồn không? Nếu bạn có một cơ sở mã lớn thì đây có thể là rất nhiều công việc. Những lựa chọn khác tồn tại?

Bạn cũng được hoan nghênh bình luận với những câu chuyện về những gì bây giờ thất bại mà trước đây sẽ vượt qua.

Những câu chuyện kinh dị về những gì bây giờ thất bại

công cụ wsimport

wsimportcông cụ là một trình tạo mã để tạo người tiêu dùng dịch vụ web. Nó được bao gồm trong JDK. Ngay cả khi bạn sử dụng wsimportcông cụ từ JDK8, nó vẫn sẽ tạo mã nguồn không thể được biên dịch bằng trình biên dịch javadoc từ JDK8 .

@ Tác giả thẻ

Tôi đang mở các tệp mã nguồn 3-4 năm tuổi và thấy điều này:

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

Điều này bây giờ thất bại vì <ký tự. Nói đúng ra điều này là hợp lý, nhưng không tha thứ cho lắm.

Bảng HTML

Bảng HTML trong Javadoc của bạn? Hãy xem xét HTML hợp lệ này:

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

Điều này bây giờ thất bại với thông báo lỗi no summary or caption for table. Một cách khắc phục nhanh là làm như thế này:

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

nhưng tại sao điều này phải là một lỗi thế giới từ công cụ Javadoc đánh bại tôi ??

Những điều bây giờ thất bại vì những lý do rõ ràng hơn

1. Liên kết không hợp lệ, vd {@link notexist}
2. HTML không đúng định dạng, ví dụ: always returns <code>true<code> if ...

CẬP NHẬT

Liên kết:

Blog tuyệt vời về chủ đề của Stephen Colebourne .

Hiện tại, cách dễ nhất mà tôi biết để làm việc xung quanh Java 8 Javadoc chặt chẽ hơn khi sử dụng Maven là tắt nó.

Do tham số -Xdoclint:nonechỉ tồn tại trong Java 8, nên việc xác định tham số này phá vỡ bản dựng cho bất kỳ Java nào khác. Để ngăn chặn điều này, chúng tôi có thể tạo một hồ sơ sẽ chỉ hoạt động cho Java 8, đảm bảo giải pháp của chúng tôi hoạt động bất kể phiên bản Java.

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

Chỉ cần thêm nó vào POM của bạn và bạn sẽ ổn.

Đối với người dùng maven-javadoc-plugin 3.0.0:

Thay thế

<additionalparam>-Xdoclint:none</additionalparam>

bởi

<doclint>none</doclint>

Cảm ơn @banterCZ!

Nếu bạn đang sử dụng plugin maven javadoc, bạn có thể sử dụng failOnErrortùy chọn để ngăn chặn nó dừng lại nếu nó tìm thấy bất kỳ lỗi html nào:

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

Hoặc bạn có thể hủy hoàn toàn các tùy chọn html nghiêm ngặt bằng:

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

Để biết thêm thông tin .

Kể từ phiên bản 3.0.0 của maven-javadoc-plugin, doclint được cấu hình thông qua thẻ XML chuyên dụng

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

Tôi thích giải pháp của @ ThiagoPorciúncula nhưng nó không đủ xa đối với tôi.

Tôi thường đã có additionalparambộ plugin javadoc không bị ghi đè bởi hồ sơ. Vì điều này tôi đã phải:

• Đặt thuộc disableDoclinttính để trống theo mặc định.
• Nếu trong java> = 8, đặt thuộc disableDoclinttính thành-Xdoclint:none
• Việc sử dụng ${disableDoclint} in thethêm section of themaven-javadoc-plugin`.

Điều này dường như hoạt động tốt mặc dù dài dòng.

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

Sau đó xuống bên dưới tôi có thể sử dụng ${disableDoclint}biến tùy chọn trong additionalparamphần mà tôi đã xác định.

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

Điều này hoạt động theo java 8 nhưng không gây ra lỗi cú pháp trong java 7. Woo hoo!

Lưu ý rằng đối với lỗi no summary or caption for table, sử dụng <table summary="">sẽ không hoạt động nữa. Nếu đó là tình huống của bạn, hãy thêm một <caption>yếu tố vào bảng của bạn, như thế này:

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

Hy vọng điều này sẽ giúp ai đó ngoài kia. Phải mất một lúc cho đến khi tôi phát hiện ra điều này.