CODEWITHSUNDEEP
javagradlejavadoc
Ryan Bis
Ryan Bis

Reputation: 343

Javadoc Exclude causing errors on import

I'm looking to tweak the javadocs for the library my company produces. We're looking to exclude javadocs from classes that aren't really meant for public consumption (mostly classes used internally).

The project uses gradle as the build system, and I've marked the packages/classes that we want to exclude in the build.gradle file. However, this is causing errors to happen. I expect to get a warning, or error if there's @link to a class which is excluded, but it's also throwing errors when those excluded classes are simply imported. Is there a way to "include" the classes/packages, but NOT export the javadoc for them?

Edit: Here's the relevant javadoc task:

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"
}

Edit 2: Here's the error I'm talking about:

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

Edit 3:

It appears that exclude in a gradle javadoc task is NOT the same thing as using -exclude on the command line with javadoc. I ran a test using CLI javadoc generation, and I did NOT get the not found errors that I do when using Gradle.

I have also posted this on the Gradle forum but did not receive an answer there.

Upvotes: 16

Views: 4591

Answers (2)

Patrick
Patrick

Reputation: 35224

So the problem is you have to tell the Javadoc task where the external imports are located, so it can creates (Hyper)-links to it in the Javadoc HTML. If you don't care about links to external classes you could ignore theses issues with:

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

According to the Gradle Doc:

Specifies whether this task should fail when errors are encountered during Javadoc generation. When true, this task will fail on Javadoc error. When false, this task will ignore Javadoc errors

Upvotes: 0

Stefan Bormann
Stefan Bormann

Reputation: 693

Javadoc needs to know about the imported class. Tell javadoc where to find the class files rather than the java source code with the classpath!

I had the same problem with XJC generated code that generates numerous javadoc errors in an ant environment. In order to exclude them from docs but still satisfy javadoc I simply told the javadoc task to look into the bin folder:

<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>

Upvotes: 4

Related Questions