使用javadoc忽略小错误

Question

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

但是使用javadoc,即使在Ant文件中,我也因为愚蠢的事情而无法生成这个,特别是"包XXX不存在"和"找不到符号"......我只想让javadoc放入这些文本html文档中的东西(外部引用),但要记录它找到的所有.java文件...

NB对于任何感兴趣的人来说这是包含下载文件(包含源代码)的下载页面,我正在尝试生成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)关于未找到的符号(虽然如果我可以解决丢失的包错误,这可能会消失).

注意,构建被认为是成功的,但我得到的投诉是没有找到源文件(确实有评论的.java文件),并且在\ javadoc下根本没有生成html.

之后,继Tony Pierce成功制作这些文档之后

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

[javadoc] D:\ Desktop\Downloads\logback-1.1.7.ta​​r\logback-1.1.7\logback-core\src\test\java\ch\qos\logback\core\appender\ConsoleAppenderTest.java:32:错误:包org.junit不存在
[javadoc] import static org.junit.Assert.assertEquals;
[javadoc] _______________________ ^

[javadoc] javadoc:错误 - 找不到要发布的公共或受保护类.
[javadoc] 1错误
[javadoc] 100警告建立

成功总时间:2秒

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

NB关于上面的"包不存在"错误(还有很多其他的):这个特别神秘,因为我认为Ant默认包含junit(NB我是Ant的一个完整的新手,只是通过"Ant in Action" ).

但是...... 根据这本让Ant自己被包含在内的Ant javac任务,你可以设置includeAntRuntime="true"它junit.jar.不幸的是,该javadoc任务不支持此属性.

后来还是

我的想法有点混乱,说实话:我发现从第三方源jar编译javadocs的最简单方法就是提取然后使用命令行,通常是:

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

...... javadoc对于一个人自己的代码,这在Gradle中似乎不是问题(我只是瞥见Ant,意识到未来是Gradle ......并且掌握基础知识并不是特别困难) .

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

申请插件:'eclipse'

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

Answer 1

使用 Java 9 或更高版本的自定义 Doclet 的编译错误

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

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

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

Answer 2

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

另请参阅:在JDK 8 Javadoc中关闭doclint

例如,在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>