java - 使用 javadoc 忽略小错误

Question

我正在尝试使用 javadoc 从一个或两个下载的 jar 文件生成文档(在提取所有内容之后，当然还有源代码)。

但是使用 javadoc，即使在 Ant 文件中，由于一些愚蠢的事情，特别是“包 XXX 不存在”和“找不到符号”，我被阻止生成这个...我只想让 javadoc 把这些东西(外部引用)在 html 文档中的文本，但要记录它找到的所有 .java 文件...

请注意，对于任何感兴趣的人，这是带有下载文件(包含源代码)的下载页面，我试图从中生成 API 文档:http://logback.qos.ch/download.html

在 Mark Rotteveel 的帮助下，我的 Ant 构建文件现在看起来像这样:

<?xml version="1.0" ?>
<project name="document logback core" default="doc">
    <target name="doc">
        <mkdir dir="javadoc" />
        <property name="excludedPackages"
            value="org.codehaus.*,javax.mail.*"/>
        <javadoc destdir="javadoc" sourcepath="src" packagenames="main.*" 
        excludepackagenames="${excludedPackages}"
        additionalparam="-Xdoclint:none" />
    </target>
</project>

...但它仍然给出错误 1) 关于未找到的包，包括“org.codehaus.[xxx...]”和“javax.mail.[xxx...]”和 2) 关于符号找不到(尽管如果我能解决丢失的包错误，这可能会消失)。

NB 据说构建成功，但我收到关于找不到源文件的投诉(确实有注释的 .java 文件)，并且在\javadoc 下根本没有生成任何 html。

后来，在 Tony Pierce 成功生成这些文档之后

安装了 Ant 1.9.6，相应地更改了路径，检查以确保这是正在使用的版本...再次尝试。又失败了。这是我输出的结尾:

[javadoc] D:\Desktop\Downloads\logback-1.1.7.tar\logback-1.1.7\logback-core\src\test\java\ch\qos\logback\core\appender\ConsoleAppenderTest.java:32: error: package org.junit does not exist
[javadoc] import static org.junit.Assert.assertEquals;
[javadoc]_______________________^

[javadoc] javadoc: error - No public or protected classes found to document.
[javadoc] 1 error
[javadoc] 100 warnings

BUILD SUCCESSFUL Total time: 2 seconds

它确实创建了 javadoc 文件夹...但这是空的。

注意上面的“包不存在”错误(还有很多其他错误):这个特别令人困惑，因为我认为 Ant 以某种方式默认包含 junit(注意我是 Ant 的新手，只是通过“Ant在行动中”)。

但是...使用 Ant javac 任务，您可以设置 includeAntRuntime="true" ...根据这本制作 Ant 自己的 junit 的书。 jar 被包括在内。不幸的是，javadoc 任务不支持此属性。

稍后

老实说，我的想法有点困惑:我发现从第三方源 jar 编译 javadoc 的最简单方法就是提取然后使用命令行，通常是:

javadoc -d docs -Xmaxwarns 10 -Xmaxerrs 10 -Xdoclint:none -sourcepath . -subpackages ch.qos.logback.core

... 至于 javadoc 对于自己的代码，这在 Gradle 中似乎不是问题(我只是瞥了一眼 Ant，意识到 future 是 Gradle ...掌握基础知识并不是特别困难)。

注意如果您为 Eclipse 安装 Gradle STS 插件，然后使用 Gradle STS 向导创建一个新项目，您的构建文件包含以下行

apply plugin: 'eclipse'

... 其中一个影响是默认情况下，所有第三方依赖项的源代码和可执行文件将在构建期间下载到 GRADLE_HOME 下。不错!

Answer 1

Java 8 引入了 doclint，它会将某些问题视为错误而不生成文档。可以通过指定命令行选项 -Xdoclint:none 来禁用它。

另请参阅:Turning off doclint in JDK 8 Javadoc

例如，在 Ant 中，您需要向 javadoc 任务添加一个 additionalparam="-Xdoclint:none" 属性。来自 Jaybird 的(稍作修改的)示例:

<target name="javadocs" depends="init,set-driver-sources">
    <mkdir dir="${build.docs}"/>
    <javadoc destdir="${build.docs}"
             author="true"
             version="true"
             windowtitle="${Name} API"
             doctitle="${Name}"
             extdirs="${module.thirdparty}"

             additionalparam="-Xdoclint:none"

             excludepackagenames="${excludedPackages}"
             bottom="Copyright &#169; 2001-2015 Jaybird (Firebird JDBC/JCA) team. All rights reserved.">
        <arg line="${java.module.arg}"/>
        <classpath refid="javac.driver.classpath"/>
        <sourcepath>
            <pathelement path="${source.java}"/>
            <pathelement path="${source.jna-client}"/>
        </sourcepath>
        <sourcepath refid="source.java.openoffice"/>
        <sourcepath refid="source.java.additional"/>
        <link href="http://docs.oracle.com/javase/7/docs/api/"/>
    </javadoc>
</target>