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）关于符号没有找到（虽然如果我可以解决丢失的包错误，这可能会消失）。

注意，构建被认为是成功的，但是我得到的投诉是没有找到源文件（确实存在注释的.java文件），并且在\ javadoc下根本没有生成html。

之后，跟随Tony Pierce成功生成这些文档

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

[javadoc的]   d：\桌面\下载\的logback-1.1.7.tar \的logback-1.1.7 \的logback核\ SRC \测试\ java中\ CH \的QoS \的logback \芯\附加器\ ConsoleAppenderTest.java：32：   错误：包org.junit不存在
[javadoc] import static   org.junit.Assert.assertEquals;
[的Javadoc] _______________________ ^

[javadoc] javadoc：错误 - 找不到公共或受保护的类   文献。
[javadoc] 1错误
[javadoc] 100警告

BUILD SUCCESSFUL总时间：2秒

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

关于上面的“包不存在”的错误（还有很多其他的）：这个特别神秘，因为我认为Ant默认包含junit（NB我是Ant的一个完整的新手，只是通过“Ant”在行动“）。

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

以后仍然

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

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向导创建一个新项目，您的构建文件包含该行

申请插件：'eclipse'

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

Answer 1

Java 8引入了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

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

下载了logback zip
将源内的jars扩展到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。

Answer 3

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

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

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

未记录-classpath选项。也许是因为将来可能会删除它。干净的方法是将所有必需的库添加到类路径（通过'log-format-upstream': '{ "app": "nginx", "time":"$time_iso8601", "remote_addr":"$remote_addr", "remote_user":"$remote_user", "forwarded_for":"$http_x_forwarded_for", "host":"$host", "res_status":"$status", "res_body_size":"$body_bytes_sent", "res_size":"$bytes_sent", "req_id":"$req_id", "req_uri":"$uri", "req_time":"$request_time", "req_proto":"$server_protocol", "req_query":"$query_string", "req_length":"$request_length", "req_method":"$request_method", "agent":"$http_user_agent", "up_name": "$proxy_upstream_name", "up_addr": "$upstream_addr", "up_res_status": "$upstream_status", "up_res_time": "$upstream_response_time", "up_res_length": "$upstream_response_length" }'选项实际解决编译错误）。

使用javadoc忽略小错误

3 个答案: