Javadoc 排除导致导入时出错

java javadoc gradle

2022-09-04 23:19:22

我正在寻求为我公司生产的库调整javadocs。我们希望将javadocs排除在那些实际上不适合公众使用的类（主要是内部使用的类）之外。

该项目使用 gradle 作为构建系统，并且我已经标记了我们要在 build.gradle 文件中排除的包/类。但是，这会导致错误发生。如果对被排除的类@link，我希望得到警告或错误，但是当这些排除的类被简单地导入时，它也会产生错误。有没有办法“包含”类/包，但不为它们导出javadoc？

编辑：这是相关的javadoc任务：

task gendocs(type: Javadoc) {
    options.stylesheetFile = new File("./assets/doc_style.css")
    String v = "${SEMVER}"
    version = v.replace("_", '.')
    title = "SweetBlue ${version} API"
    options.windowTitle = "SweetBlue"
    options.memberLevel = JavadocMemberLevel.PROTECTED
    options.author = true
    options.linksOffline('http://d.android.com/reference', System.getenv("ANDROID_HOME") + '/docs/reference')    
    destinationDir = new File("${BUNDLE_FOLDER}/docs/api")
    source = sourceSets.main.allJava
    classpath += configurations.compile
    exclude "com/idevicesinc/sweetblue/backend"
    exclude "com/idevicesinc/sweetblue/utils/Utils**.java"
    exclude "com/idevicesinc/sweetblue/utils/UpdateLoop.java"
    exclude "com/idevicesinc/sweetblue/utils/Pointer.java"
    exclude "com/idevicesinc/sweetblue/utils/HistoricalDataQuery.java"
}

编辑2：这是我所说的错误：

SweetBlue/src/com/idevicesinc/sweetblue/BleCharacteristic.java:5: error: cannot find symbol
import com.idevicesinc.sweetblue.utils.Utils;                                      
symbol:   class Utils
location: package com.idevicesinc.sweetblue.utils

编辑3：

看起来在 gradle javadoc 任务中排除与在带有 javadoc 的命令行上使用 -exclude 不是一回事。我使用CLI javadoc生成运行了一个测试，但是我没有收到使用Gradle时未找到的错误。

我也在Gradle论坛上发布了这个，但没有收到答案。

答案 1

Javadoc 需要了解导入的类。告诉javadoc在哪里可以找到类文件，而不是带有类路径的java源代码！

我在XJC生成的代码中遇到了同样的问题，该代码在ant环境中生成了许多javadoc错误。为了将它们从文档中排除，但仍然满足javadoc，我只是告诉javadoc任务查看bin文件夹：

<target name="javadoc" description="create Javadoc documentation">
    <javadoc ...lots of irrelevant attributes skipped...>
        <fileset dir="src">
            <include name="**/*.java"/>
            <exclude name="my/jaxb/generated/source/*.java"/>
        </fileset>
        <classpath>
            <path refid="myclasspath_to_referenced_libraries"/>
            <pathelement location="bin"/>
        </classpath>
    </javadoc>
</target>

答案 2

所以问题是你必须告诉Javadoc任务外部导入的位置，这样它就可以在Javadoc HTML中创建（Hyper）链接到它。如果您不关心指向外部类的链接，则可以忽略以下问题：

task gendocs(type: Javadoc) {
    failOnError false
    ...
}

根据Gradle Doc：

指定在 Javadoc 生成期间遇到错误时，此任务是否应失败。如果为 true，则此任务将在 Javadoc 错误时失败。如果为 false，此任务将忽略 Javadoc 错误