忽略Javadoc中的小错误

Question

忽略Javadoc中的小错误

18

我正在尝试使用javadoc从一个或两个已下载的jar文件（当然，是在提取了所有内容后）生成文档。

但是由于一些愚蠢的原因（特别是“包XXX不存在”和“找不到符号”），即使在Ant文件中使用javadoc，我也被阻止生成文档。我只想让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>

...但仍然出现错误，其中包括“org.codehaus.[xxx...]”和“javax.mail.[xxx...]”未找到的包，以及符号未找到（尽管如果我可以解决丢失的软件包错误，则可能会消失）。

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文件夹...但是这是空的。

NB关于上面的“包不存在”错误（还有许多其他错误）：我想Ant默认情况下以某种方式包括junit（NB我是Ant的完全新手，只是通过“Ant in Action”进行工作）。

但是...使用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，意识到未来是Gradle...掌握基础并不特别困难）。

NB如果在Eclipse中安装Gradle STS插件，然后使用Gradle STS向导创建新项目，则构建文件包含以下行：

apply plugin: 'eclipse'

...其中的一个影响是默认情况下，在构建期间下载所有第三方依赖项的源以及可执行文件，这非常好！

- mike rodent

4个回答

8

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

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

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

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

- Marteng

感谢 --ignore-source-errors 选项。 :) - Christopher

这个问题是由于我需要从文档中排除“internal”包所致。这个解决方案适用于一个在Java 11上失败的Javadoc gradle任务（之前在Java 8上运行正常）。为什么这个选项没有被记录下来，对我来说是个谜。 - franmontiel

@Marteng，你会如何在Gradle任务中精确地声明这个选项？ - Ivan Garza

0

我简化了您的构建文件，并成功地构建了javadoc。这是我做的：

下载了logback zip文件
将源代码jar包解压到src目录中

使用以下命令在java 8下运行ant 1.9.6：

<?xml version="1.0" ?>
<project name="document logback core" default="doc">
    <target name="doc">
        <mkdir dir="javadoc" />
        <javadoc destdir="javadoc" sourcepath="src" 
            additionalparam="-Xdoclint:none" />
    </target>
</project>

它产生了很多警告，但创建了一个充满HTML的javadoc目录。

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

- Tony Pierce

谢谢。我试过了，没有生成任何HTML或其他内容。唯一的区别是我使用的是Ant 1.9.7！在周末，我会尝试找时间使用Ant 1.9.6……难道这是一个神秘的Windows权限问题吗？ - mike rodent

0

除了上面的答案之外，当使用ANT: 1.10.13和Java: 17.0.6时，我的构建无法完成，因为出现了javadoc错误。将additionalparam属性添加到javadoc任务中没有起作用，但是对于每个参数使用arg元素可以解决问题。

<javadoc>
    <arg value="--ignore-source-errors"/>
    <arg value="-Xdoclint:none"/>
</javadoc>

通过这个javadoc，仍然生成了HTML，并且我的构建成功了。

- ptha

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- Mark Rotteveel · Accepted Answer

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

另请参阅：关闭JDK 8 Javadoc中的doclint

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