Javadoc exclusion question

Help/Discuss
1

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

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?

Error:

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

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"
}
1 Like
2

So it seems that exclude in gradle does NOT do the same thing as -exclude when using javadoc on the command line.

When using the command line, I don’t get the errors. When using gradle, I do.

3

So is there any reason why gradle fails at this task, compared to doing it in the command line? We were hoping to keep as much as possible in our gradle script, but if it can’t exclude packages/classes properly without screwing up the whole build, then we’ll have to just generate the docs outside of gradle.

4

I’m not positive, but I think this might be related to gradle feeding javadoc individual files rather than whole packages, and the exclude directive being gradle SourceTask's rather than javadoc’s.

5

I solved this by adding compilation output to javadocs input like so:

classpath = it.sourceSets.main.compileClasspath + it.sourceSets.main.output
```
6

@fab1an 's answer and specifically, classpath += sourceSets.main.output made it work for me for Java modules.

However, I can’t use that configuration on an Android-library module for javadoc generation. In my case, this is the Javadoc configuration I use for an Android-library module:

task gendocs(type: Javadoc) {
         ...
        source = android.sourceSets.main.java.srcDirs
        classpath += project.files(android.getBootClasspath())
        android.libraryVariants.all { variant ->
            if (variant.name == 'release') {
                owner.classpath += variant.javaCompileProvider.get().classpath
            }
        }
       ...
}

If I add the path to the generated classes by hand, it works:

classpath += project.files("$buildDir/intermediates/javac/debug/classes")

But this is a bit hacky and it will fail if the Javadoc task runs before the classes are generated.

What is the proper way to get the generated classes in an Android module using Gradle and AGP?

7

I found a solution, based on this question, for Javadoc generation in Android or Android-library modules when excluding files:

afterEvaluate {
     task gendocs(type: Javadoc) {
                ...
                classpath += project.files(compileDebugJavaWithJavac.destinationDirectory)
                ...
     }
}