使用 gradle 生成 android 库的 javadoc 时排除内部 java 类

Question

I'm trying to build the javadoc for a library which contains some internal classes which are not relevant for the developers. Previously with java 1.6 I was able to exclude the classes I don't want to appear in the javadoc using the exclude option, But since java 8 this is not the case anymore. When I use the exclude option the classes are just removed and the javadoc lint throws an error because other classes need the internal classes which I want to exclude. Here the example:

task javadoc(type: Javadoc) {
    // failOnError false -> This will tell gradle the job was successful but nothing is generated
    source = android.sourceSets.main.java.sourceFiles
    exclude 'com/example/customlib/internal/Utils.java'
}

Running the task throws the following error:

[..]/customlib/src/main/java/com/example/customlib/Foo.java:3: error: package com.example.customlib.internal does not exist

After searching a solution I came across many proposals but non of them worked. It appears the javadoc lint is firing the error when it generates the docs. Then I've tried disabling the lint for the specific file as follows:

task javadoc(type: Javadoc) {
    source = android.sourceSets.main.java.sourceFiles
    exclude 'com/example/customlib/internal/Utils.java'
    options.addStringOption('Xdoclint:none src/main/java/com/example/customlib/internal/Utils.java', '-quiet')
}

Now the tasks succeed but the classes I want to exclude are present in the generated javadoc.

Does anybody knows how to remove specific classes/packages from the generated javadoc?

Answer 1

After more investigation I found the way to exclude files from the javadoc. Apparently there is a bug in the gradle task and the following workaround will allow the javadoc task to finish gratefully

task javadoc(type: Javadoc) {
    source = android.sourceSets.main.java.sourceFiles
    exclude 'com/example/customlib/internal/Utils.java'

    // The following lines will workaround the problem with the exclude
    var sourceSetDirectories = android.sourceSets.main.java.srcDirs.join(":")
    options.addStringOption("-source-path", sourceSetDirectories)
}

If the library has references to other libs like androidx or android classes, add the classpath parameter and option.links :

task javadoc(type: Javadoc) {
    // failOnError false -> This will tell gradle the job was successful but nothing is generated
    source = android.sourceSets.main.java.sourceFiles
    classpath += project.files(android.getBootClasspath().join(File.pathSeparator))
    options {
        links "http://docs.oracle.com/javase/7/docs/api/"
        linksOffline('https://d.android.com/reference/', 'https://d.android.com/reference/androidx/')
    }

    exclude 'com/example/customlib/internal/Utils.java'

    // The following lines will workaround the problem with the exclude
    var sourceSetDirectories = android.sourceSets.main.java.srcDirs.join(":")
    options.addStringOption("-source-path", sourceSetDirectories)
}