用於Java API核心類的maven-javadoc-plugin和inheritDoc

我正在編寫自己的Java 8 Stream實現，並希望從原始java.util.stream.Stream接口繼承Javadoc。但是我無法得到它的工作。生成的Javadoc僅顯示我的文檔，但不顯示擴展的Stream接口中的文檔。用於Java API核心類的maven-javadoc-plugin和inheritDoc

例如，此方法的javadoc只包含文本「一些附加信息」，但不包含來自Stream接口的文檔。

/** 
* {@inheritDoc} 
* Some additional information. 
*/ 
@Override 
public Stream<T> filter(Predicate<? super T> predicate) { 
    // ... my stream implementation... 
}

這是我的Maven的Javadoc的插件的配置：

<plugin> 
    <groupId>org.apache.maven.plugins</groupId> 
    <artifactId>maven-javadoc-plugin</artifactId> 
    <version>2.10.1</version> 
    <configuration> 
    <links> 
     <link>http://docs.oracle.com/javase/8/docs/api/</link> 
    </links> 
    </configuration> 
</plugin>

難道我錯過這個配置的東西嗎？我在maven-compiler-plugin中將source和target設置爲1.8。所以根據maven-javadoc-plugin的文檔，應該自動檢測到java API。

Stack Overflow上也有一個similar question，但那裏的答案似乎沒有幫助。

來源

2016-08-01 Stefan Ferstl

這是預期的，javadoc只複製源路徑中的類的註釋。從Method Comment Inheritance：

注：爲繼承的方法的源文件必須由-sourcepath選項指定的路徑上的文檔註釋可用複製的。在命令行上不需要傳入類或它的包。這與版本1.3.n和更早版本形成對比，其中類必須是記錄類。

但是，您的JDK的源代碼不在源路徑中，因此{@inheritDoc}將不會複製它。他們需要明確地添加;在Javadoc FAQ has this entry：從J2SE

傳承評論 - 您的代碼還可以自動繼承從J2SE接口和類評論。您可以通過解壓縮SDK附帶的src.zip文件（但它不包含所有源文件）並將其路徑添加到-sourcepath來完成此操作。當您的代碼運行javadoc時，它將根據需要從這些源文件加載文檔註釋。例如，如果代碼中的某個類實現java.lang.Comparable，則您實現的compareTo(Object)方法將從java.lang.Comparable繼承doc註釋。

所以，使其工作：

找到你的JDK的來源和地方對其進行解壓縮。

配置maven-javadoc-plugin以使用sourcepath參數添加這些源。

通過上面的介紹，我們也會生成JDK本身的Javadoc，這是不必要的（我們只想繼承），所以我們可以使用subpackages來指定我們的包。或者，我們可以使用excludePackageNames來排除JDK軟件包。

JDK（至少Oracle JDK）也使用新的Javadoc條目，即@apiNote,@implSpec和@implNote。這些是需要與tags參數一起添加的自定義標籤。

下面是一個簡單的配置，其中路徑JDK來源是/path/to/jdk/sources（你也可以使用一個環境變量，屬性由配置文件中設置等）和自己的源文件都在包my.package：

<plugin> <groupId>org.apache.maven.plugins</groupId> <artifactId>maven-javadoc-plugin</artifactId> <version>2.10.1</version> <configuration> <sourcepath>/path/to/jdk/sources:${basedir}/src/main/java</sourcepath> <subpackages>my.package</subpackages> <tags> <tag> <name>apiNote</name> <placement>a</placement> <head>API Note:</head> </tag> <tag> <name>implSpec</name> <placement>a</placement> <head>Implementation Requirements:</head> </tag> <tag> <name>implNote</name> <placement>a</placement> <head>Implementation Note:</head> </tag> </tags> </configuration> </plugin>

生成的Javadoc，例如用mvn javadoc:javadoc，將正確解析{@inheritDoc}。

來源

2016-08-01 21:25:28 Tunaki

謝謝，這工作。我還設法在maven構建過程中通過將'system'作用域依賴聲明聲明爲'$ {java.home} /../ src.zip'來直接提取'src.zip'。有了這個依賴關係，我可以使用maven-dependency-plugin的unpack-dependencies目標，包含我需要的包。對於'java.util'包（我不需要更多），這隻需要幾秒鐘。 –

用於Java API核心類的maven-javadoc-plugin和inheritDoc

回答

相關問題