Maven을 사용할 때 더 엄격한 Java 8 Javadoc을 해결하는 방법

JDK8이 Javadoc과 관련하여 훨씬 더 엄격하다는 것을 금방 알 수 있습니다. ( 링크 -마지막 글 머리 기호 참조)

Javadoc을 생성하지 않으면 물론 문제가 발생하지 않지만 Maven 릴리스 프로세스 및 CI 빌드와 같은 것은 JDK7에서 제대로 작동하면 갑자기 실패합니다. Javadoc 도구의 종료 값을 확인하는 것은 이제 실패합니다. JDK8 Javadoc은 아마도 JDK7에 warnings비해 더 장황 하지만 아마도 여기에 해당되지 않습니다. 우리는 이야기하고 있습니다 errors!

이 질문은 그에 대한 제안을 수집하기 위해 존재합니다. 가장 좋은 방법은 무엇입니까? 소스 코드 파일에서 이러한 오류를 한 번만 수정해야합니까? 거대한 코드 기반이 있다면 많은 작업이 필요할 수 있습니다. 다른 옵션은 무엇입니까?

당신은 또한 이전에지나 갔던 지금 실패한 것에 대한 이야기로 의견을 환영합니다.

지금 실패한 것에 대한 공포 이야기

wsimport 도구

wsimport도구는 웹 서비스 소비자를 만들기위한 코드 생성기입니다. JDK에 포함되어 있습니다. wsimportJDK8 의 도구 를 사용하더라도 JDK8 의 javadoc 컴파일러로 컴파일 할 수없는 소스 코드 가 생성됩니다 .

@ 저자 태그

3-4 세의 소스 코드 파일을 열어 보았습니다.

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

<문자로 인해 이제 실패합니다. 엄밀히 말하면 이것은 정당하지만 용서하지는 않습니다.

HTML 테이블

Javadoc의 HTML 테이블? 이 유효한 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 ...

최신 정보

연결:

Stephen Colebourne 의 주제 에 관한 훌륭한 블로그 .

지금까지 Maven을 사용할 때 더 엄격한 Java 8 Javadoc 을 해결 하는 가장 쉬운 방법 은 비활성화하는 것입니다.

매개 변수 -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>

더에 대한 정보 .

maven-javadoc-plugin 버전 3.0.0부터 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 theadditionalparam은 section of the받는다는 - 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>

이것이 누군가를 도울 수 있기를 바랍니다. 내가 이것을 발견 할 때까지 시간이 걸렸습니다.