Maven:依赖关系驱动的Javadoc聚合和自定义doclet [英] Maven: Dependency-driven javadoc aggregation and custom doclet
问题描述
我已经准备了一个非常简单的演示,演示了我想做的更大的事情来演示该问题:
I've prepared a very simple demo of what I would like to do in much bigger scale to demonstrate the issue:
配置:java 1.8,maven 3.3.9,maven-javadoc-plugin 3.0.1
Configuration: java 1.8, maven 3.3.9, maven-javadoc-plugin 3.0.1
我有Maven工件testA,testB和testC.组件testA是一个Javadoc聚合器项目. B类(位于testB组件中)导入并实例化C类(位于testC组件中).
I've got maven artifacts testA, testB and testC. Component testA is a javadoc aggregator project. Class B (located in testB component) imports and instantiates class C (located in testC component).
testA直接依赖于testB,而testB直接依赖于testC(均提供了作用域),因此testA对testC具有传递依赖.
testA has a direct dependency on testB and testB has direct dependency on testC (both with scope provided), thus testA has transitive dependency on testC.
此外,使用自定义的javadoc标记来标记B类.
In addition, class B is tagged with a custom javadoc tag.
由于我没有编写doclet的经验,因此我使用了在互联网上找到的 doclet 并根据我的需要进行了修改(基本上,我只是重写了exclude方法以仅包含包含自定义标记的类文档).
As I have no experience with writing doclets, I used a doclet I found on the internet and modified it to my needs (basically I just rewrote exclude method to include only class docs containing the custom tag).
如上所述,testA是一个聚合器,旨在仅从直接(非传递性)依赖项中收集依赖项源,并仅为标记的类生成javadoc.这需要任何直接依赖项来在构建过程中捆绑其源代码,因此我使用maven-source-plugin从组件testB生成源工件.
As mentioned above, testA is an aggregator, which is intended to gather dependency sources from direct (non-transitive) dependencies only and generate javadoc for tagged classes only. This requires any direct dependencies to bundle their source codes during the build, so I use maven-source-plugin to generate source artifact from component testB.
现在,问题是,当我运行maven javadoc插件时,此异常失败:
Now, the problem is, when I run maven javadoc plugin, it fails on this exception:
[ERROR] java.lang.ArrayIndexOutOfBoundsException: 0
[ERROR] at com.sun.tools.doclets.formats.html.ConfigurationImpl.setTopFile(ConfigurationImpl.java:537)
该异常指向此行:
this.topFile = DocPath.forPackage(this.packages[0]).resolve(DocPaths.PACKAGE_SUMMARY);
似乎没有要处理的包裹.但是,我确信doclet在单个组件上执行时会按预期工作(非聚合用法,在没有maven的情况下尝试使用-javadoc cmd).当我使用Standard doclet时,整个聚合过程也可以正常工作,但这对我来说并没有用,因为我真的只需要包含标记的类.
It seems like there is no package to be processed. However I am sure the doclet works as intended when executed on a single component (non-aggregation usage, tried without maven - javadoc cmd). Also the whole aggregation thing works when I use the Standard doclet, but that's not of use for me as I really need to include only the tagged classes.
这是我的聚合器的POM.xml:
Here is my aggregator's POM.xml:
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>test</groupId>
<artifactId>testA</artifactId>
<version>1</version>
<dependencies>
<dependency>
<groupId>com.sun</groupId>
<artifactId>tools</artifactId>
<version>1.8</version>
<scope>system</scope>
<systemPath>${java.home}/../lib/tools.jar</systemPath>
</dependency>
<dependency>
<groupId>test</groupId>
<artifactId>testB</artifactId>
<version>1</version>
<scope>provided</scope>
</dependency>
</dependencies>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>3.0.1</version>
<configuration>
<destDir>testOutput</destDir>
<includeDependencySources>true</includeDependencySources>
<doclet>com.test.MyDoclet</doclet>
<docletArtifact>
<groupId>test</groupId>
<artifactId>my-doclet-artifact</artifactId>
<version>1</version>
</docletArtifact>
<useStandardDocletOptions>true</useStandardDocletOptions>
<tags>
<tag>
<name>MyTag</name>
</tag>
</tags>
</configuration>
</plugin>
</plugins>
</build>
</project>
我做错了什么?有人可以帮我吗?
What am I doing wrong? Could someone help me, please?
推荐答案
实际上,我设法使其正常运行.问题出在doclet代码上.我不知道javadoc如何处理代码元素.
Actually, I managed to make it work. Problem was with the doclet code. I didn't know how the javadoc processes the code elements.
有一个从RootDoc节点开始的树结构.从那里走下来,这棵树. RootDoc->包->类->成员等 由于我仅处理标记的类,因此其他所有内容均被跳过.因此,递归从一开始就被打破了-PackageDoc元素都没有通过该条件,因此最后没有任何处理.
There is a tree structure starting with RootDoc node. From there it walks this tree down. RootDoc -> packages -> classes -> members etc. Since I processed tagged classes only, everything else was skipped. Thus recursion was broken right at the beginning - none of the PackageDoc elements passed the condition, so nothing was processed in the end.
我可以存储(包括)我想要的javadoc,但是无论处理哪种类型的元素,我都必须确保递归继续进行.
I can store (include) whatever I want for the javadoc, but I have to ensure recursion continues no matter what type of element is processed.
这篇关于Maven:依赖关系驱动的Javadoc聚合和自定义doclet的文章就介绍到这了,希望我们推荐的答案对大家有所帮助,也希望大家多多支持IT屋!