java - 使用特殊 doclet 运行 Javadoc 时出现 Vague IOException

Question

这可能是一个特定于 doclet 实现的问题，但我相信我在这里处理的确实是一个 JavaDoc 配置问题。

我正在尝试获取 yDoc UML Doclet工作，以便它将为我的 Java 应用程序生成 UML 图作为 Ant 构建的一部分。我下载了该项目(社区版)并尝试调整他们的 build-sample.xml 但无法完全正常工作。

这是我的项目目录结构:

MyProject/
    src/main/java/
        <All the Java sources I want documented and diagrammed>
    bin/main
        <Compiled binaries of src/main/java/>
    lib/
        styleed.jar
        ydoc.jar
    resources/
        <All the yDoc resources that came with the download>
    umldoclet/
        <Where I want all JavaDocs to go>
    build.xml

这是build.xml:

<project name="MyProject" default="ydoc" basedir="." xmlns:ivy="antlib:org.apache.ivy.ant" xmlns:jacoco="antlib:org.jacoco.ant">

    <!-- The "compile" task and all its dependencies omitted for brevity,
         but they all absolutely work 100% and "compile" places compiled
         CLASS files under bin/main. -->

    <target name="ydoc" depends="compile">
        <property name="ydoc.home" value="${basedir}"/>

        <javadoc source="1.5" destdir="./umldoclet" additionalparam="-breakiterator">
            <packageset dir="src/main">
                <include name="java/**"/>
            </packageset>
            <doclet name="ydoc.doclets.YStandard" path="${ydoc.home}/lib/ydoc.jar;${ydoc.home}/resources">
                <param name="-author"/>
                <param name="-generic"/>
                <param name="-umlautogen"/>
                <param name="-filterpath" value="./lib/ydoc.jar"/>
                <param name="-filter" value="ydoc.filters.ExcludeFilter"/>
                <param name="-tag" value="y.precondition"/>
                <param name="-tag" value="y.postcondition"/>
                <param name="-tag" value="y.complexity"/>
                <param name="-tag" value="param"/>
                <param name="-tag" value="return"/>
                <param name="-tag" value="see"/>
                <param name="-tag" value="y.uml"/>
            </doclet>
        </javadoc>
    </target>
</project>

当我运行 ydoc 任务时，即使使用 -v 参数以“详细”模式运行 Ant，我也会看到 [ydoc] 在 Ant 控制台中调用任务，然后是一个日志语句，上面写着“生成 Javadoc”，从详细输出中大约 20 行向我反馈 yDoc 参数，最后一条日志消息说“Javadoc 执行”。然后，以下令人震惊的模糊 IOException:

BUILD FAILED
<my-eclipse-home>/MyProject/build.xml:200: Javadoc failed: java.io.IOException: Cannot run program "javadoc": java.io.IOException: error=2, No such file or directory
    at org.apache.tools.ant.taskdefs.Javadoc.execute(Javadoc.java:1765)
    at org.apache.tools.ant.UnknownElement.execute(UnknownElement.java:291)
    at sun.reflect.GeneratedMethodAccessor4.invoke(Unknown Source)
    at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
    at java.lang.reflect.Method.invoke(Method.java:616)
    at org.apache.tools.ant.dispatch.DispatchUtils.execute(DispatchUtils.java:106)
    at org.apache.tools.ant.Task.perform(Task.java:348)
    at org.apache.tools.ant.Target.execute(Target.java:392)
    at org.apache.tools.ant.Target.performTasks(Target.java:413)
    at org.apache.tools.ant.Project.executeSortedTargets(Project.java:1399)
    at org.apache.tools.ant.Project.executeTarget(Project.java:1368)
    at org.apache.tools.ant.helper.DefaultExecutor.executeTargets(DefaultExecutor.java:41)
    at org.eclipse.ant.internal.launching.remote.EclipseDefaultExecutor.executeTargets(EclipseDefaultExecutor.java:32)
    at org.apache.tools.ant.Project.executeTargets(Project.java:1251)
    at org.eclipse.ant.internal.launching.remote.InternalAntRunner.run(InternalAntRunner.java:424)
    at org.eclipse.ant.internal.launching.remote.InternalAntRunner.main(InternalAntRunner.java:138)
Caused by: java.io.IOException: Cannot run program "javadoc": java.io.IOException: error=2, No such file or directory
    at java.lang.ProcessBuilder.start(ProcessBuilder.java:475)
    at java.lang.Runtime.exec(Runtime.java:610)
    at org.apache.tools.ant.taskdefs.Execute$Java13CommandLauncher.exec(Execute.java:862)
    at org.apache.tools.ant.taskdefs.Execute.launch(Execute.java:481)
    at org.apache.tools.ant.taskdefs.Execute.execute(Execute.java:495)
    at org.apache.tools.ant.taskdefs.Javadoc.execute(Javadoc.java:1759)
    ... 15 more
Caused by: java.io.IOException: java.io.IOException: error=2, No such file or directory
    at java.lang.UNIXProcess.<init>(UNIXProcess.java:164)
    at java.lang.ProcessImpl.start(ProcessImpl.java:81)
    at java.lang.ProcessBuilder.start(ProcessBuilder.java:468)
    ... 20 more

有没有办法从 Ant 中获取更多详细信息？要找出它在异常中引用的文件或目录？以前有没有 JavaDoc/yDoc 专家遇到过这个问题？我的项目目录结构是否设置不正确，或者与 Ant 构建所寻找的不同？我相信我的 doclet/path 属性设置正确，并且使用了正确的路径分隔符(我在 Ubuntu Linux 上)。对于我的一生，我无法弄清楚从这里去哪里，或者如何在这里诊断潜在的问题!提前致谢!

编辑/更新:

感谢大家到目前为止的建议。我完全取消了 Eclipse(就构建而言，只是从命令行运行 Ant；现在这很好。当我这样做时，我得到了一个成功的构建(所以 Eclipse 至少部分是罪魁祸首), 但是仍然没有生成 yDoc。

现在，当我使用 verbos (-v) 选项从终端运行 Ant 时，这是我看到的:

数百个看起来相同但类别不同的​​警告:

[javadoc] Constructing Javadoc information...
[javadoc] /<path-to-my-project>/MyProject/src/main/java/com/some/pkg/SomeObject.java:11: package org.springframework.beans.factory.annotation does not exist
[javadoc] import org.springframework.beans.factory.annotation.Autowired;
[javadoc]                                                    ^

在数百次之后，我得到以下输出(我的源代码树中的每个包都有 1 个):

[javadoc] javadoc: warning - No source files for package java.com.some.pkg.<whatever>

最后，详细构建输出的最后一部分:

[javadoc] Valid license file found.
[javadoc] Registered Filter ydoc.filters.ExcludeFilter ...
[javadoc] Registered Taglet for tag @y.complexity ...
[javadoc] Registered Taglet for tag @y.precondition ...
[javadoc] Registered Taglet for tag @y.postcondition ...
[javadoc] Registered Taglet for tag @y.author ...
[javadoc] 1 error
[javadoc] 109 warnings
[javadoc] javadoc: error - No public or protected classes found to document.

BUILD SUCCESSFUL
Total time: 6 seconds

此外，如果它正确执行，它应该将所有 JavaDoc 放在我项目根目录的 uml-doclet/ 目录下。它不会做这样的事情!

所以看起来还有几件事情在发生:

1. JavaDoc 看不到我的第 3 方依赖项(例如 Spring、Camel 等)；因此列出了数百个警告
2. 它找不到我的任何来源来记录

再一次，赏金会奖励给任何能帮助我完成这项工作的人。再次感谢迄今为止提供的所有帮助!

Answer 1

如果用 -verbose -debug 执行 ant你会看到这些行:

Setting project property: ydoc.home -> /var/tmp/ydoc-test
  [javadoc] scanning /var/tmp/ydoc-test/src/main for packages.
dirset: Setup scanner in dir /var/tmp/ydoc-test/src/main with patternSet{ includes: [java/**] excludes: [] }
  [javadoc] Generating Javadoc
  [javadoc] Executing '/usr/lib/jvm/java-7-openjdk-amd64/bin/javadoc' with arguments:
  [...]

或者你会看到这些行:

Setting project property: ydoc.home -> /var/tmp/ydoc-test
  [javadoc] scanning /var/tmp/ydoc-test/src/main for packages.
dirset: Setup scanner in dir /var/tmp/ydoc-test/src/main with patternSet{ includes: [java/**] excludes: [] }
  [javadoc] Generating Javadoc
  [javadoc] Executing 'javadoc' with arguments:

在第一种情况下，Eclipse/Ant 找到了一个有效的 javadoc命令并在 [javadoc] Executing >FULL_PATHNAME_TO_JAVADOC> 行中告诉您.在第二种情况下，它只谈论 javadoc没有任何路径名，调试输出稍后将显示您的异常。

我假设你的情况是第二种，但请检查一下!

如果 Eclipse/Ant 不知道 javadoc 的位置您首先应该通过将 Eclipse 排除在等式之外来简化事情:使用命令行并检查键入这些命令不会导致“找不到命令”消息:

java
javac
javadoc

我假设第一个没问题(毕竟您可以运行 Eclipse，如您的堆栈跟踪所示)。如果没有找到第二条和第三条命令，则说明您的计算机上没有安装 JDK，而只是安装了 JRE。安装一个并重新启动 Eclipse。

如果另一方面javac被发现但是javadoc不是，那么你的 JDK 坏了。

如果两者都是javac和 javadoc被发现然后 Eclipse 根本不知道它。但在返回 Eclipse 之前，请在命令 shell 中键入最后一条命令:

readlink -m $(which javadoc)/../..

记住路径 readlink给你。

在 Eclipse 中转到“窗口 -> 首选项 -> Java -> 已安装的 JRE”。在列表中选择带有选中复选框的条目，然后按“编辑”。如果行“JRE home”与路径不同 readlink给了你，那么很可能你的 Eclipse 配置为只使用本地 JRE 而不是你安装的 JDK。

如果是这种情况，则取消“编辑”对话框，按“添加”，选择“标准虚拟机”并输入路径 readlink给你。正确输入该路径后，Eclipse 应会为您填写其他字段，因此您只需说“确定”即可。回到“已安装的 JRE”列表中，在新项目上打勾。

在那之后 javadoc任务本身应该开始。

编辑

但是你还需要一些调整:

首先:在这部分:

       <packageset dir="src/main">
            <include name="java/**"/>
        </packageset>

您正在混合源目录和包部分。它应该是:

       <packageset dir="src/main/java">
       </packageset>

还有 javadoc喜欢访问引用的类。因此，您应该将用于编译代码的相同类路径添加到 javadoc。所以添加一个合适的<classpath> </packageset> 之后的部分.这将处理“包 xyz 不存在”警告。