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

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>

Just add that to your POM and you're good to go.

---

For maven-javadoc-plugin 3.0.0 users:

Replace

<additionalparam>-Xdoclint:none</additionalparam>

by

<doclint>none</doclint>

Thanks @banterCZ!

---

If you are using the maven javadoc plugin, you can use the failOnError option to prevent it from stopping if it finds any html errors:

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

Or you can deactivate the strict html options completely with:

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

For more info.

---

I like @ThiagoPorciúncula's solution but it didn't quite go far enough for me.

I typically already have javadoc plugin additionalparam set which were not being overridden by the profile. Because of this I had to:

• Set a disableDoclint property to be empty by default.
• If in java >= 8, set the disableDoclint property to be -Xdoclint:none
• The use ${disableDoclint} in theadditionalparamsection of themaven-javadoc-plugin`.

This seems to work well albeit verbose.

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

Then down below I could use the optional ${disableDoclint} variable in the additionalparam section that I had already defined.

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

This works under java 8 but doesn't cause syntax errors under java 7. Woo hoo!

---

Since version 3.0.0 of maven-javadoc-plugin the doclint is configured via the dedicated XML tag

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

---

Note that for the error no summary or caption for table, using <table summary=""> won't work anymore. If that's your situation, add a <caption> element to your table, like this:

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

Hope this helps someone out there. It took me a while until I found this out.

참고URL : https://stackoverflow.com/questions/22528767/how-to-work-around-the-stricter-java-8-javadoc-when-using-maven