使用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。

稍后，继托尼皮尔斯成功地生成这些文档之后

安装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:错误:包org.junit不存在javadoc导入静态org.junit.Assert.assertEquals;javadoc_______________________^javadoc javadoc: error -没有发现document.javadoc 1错误的公共或受保护类，document.javadoc 100警告生成成功的总计时间:2秒

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

关于上面的“包不存在”错误(还有许多其他错误)：这个错误特别令人费解，因为我认为Ant在默认情况下包含了junit (NB我是Ant的一个完全新手，只是通过"Ant in Action“工作)。

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

后来仍然是

老实说，我的想法有点混乱:我发现从第三方源代码jars编译javadocs的最简单方法是提取并使用命令行，通常是：

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

..。至于javadoc本身的代码，这似乎不是Gradle中的问题(我只是瞥见了Ant，意识到未来是Gradle.掌握基本知识并不特别困难)。

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

应用插件：“eclipse”

..。其影响之一是，默认情况下，在构建过程中，所有第三方依赖项的源和可执行文件都将在GRADLE_HOME下下载。挺不错的！

Answer 1

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

另见：Turning off doclint in JDK 8 Javadoc

例如，在Ant中，您需要向additionalparam="-Xdoclint:none"任务添加一个javadoc属性。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>

Answer 2

用Java9或更高版本的自定义Doclet编译错误

-Xdoclint:none是标准doclet的一个选项，它不适用于自定义doclet。

如果您有一个自定义doclet，并且不关心编译错误，则可以将--ignore-source-errors选项传递给javadoc命令行工具，或者如果您以编程方式调用doclet，则可以将其传递给javax.tools.DocumentationTool.getTask(...)。

--ignore-source-errors选项没有文档化。也许是因为它将来可能会被移除。干净的方法是将所有必需的库添加到类路径中(通过-classpath选项实际解决编译错误)。

Answer 3

我稍微简化了构建文件，并成功地构建了javadoc。我所做的是：

• 下载了logback zip
• 将内部的源jars扩展到src目录中
• 在java 8下运行ant 1.9.6，如下所示：

它产生了很多警告，但是创建了一个包含html的javadoc目录。

我删除了excludepackagenames并删除了packagenames元素。在任何情况下，packagenames="main.*"都会阻止javadoc生成，因为jar中唯一的根包是ch和org。