Gradle exclude R.java in Android Javadocs when internal classes depend on R.java

Question

I am building JavaDoc for an API wherein classes in the API depend on R.java. I want to build the Javadoc w/o symbol errors referencing the missing R.java file as even when I set failOnError false the build succeeds but our Jenkins job will report the build as Failed when errors occur in successful builds. The task below will successfully create the javadocs but will report errors during build relating to not finding R.java.

android.libraryVariants.all { variant ->
def name = variant.name.capitalize()

task("generate${name}Doclava", type: Javadoc) {

    description "Generates Javadoc for $variant.name."
    source = variant.javaCompile.source
    title = null
    // use android.bootClasspath instead of building our own path to android jar
    //ext.androidJar = "${android.sdkDirectory}/platforms/${android.compileSdkVersion}/android.jar"
    // hardcoded path to generated R.java file to avoid javadoc compile issues
    ext.R = "build/generated/source/r/minSDK15/release"
    classpath += project.files(android.sourceSets.main.java.srcDirs, variant.javaCompile.classpath.files, android.bootClasspath)
    destinationDir = file("${project.docsDir}/${name}/doclava")
    options {
        docletpath = configurations.jaxDoclet.files.asType(List)
        doclet "com.google.doclava.Doclava"
        bootClasspath new File(System.getenv('JAVA_HOME') + "/jre/lib/rt.jar")
        addStringOption "XDignore.symbol.file", "-quiet"
        addStringOption "hdf project.name", "${project.name}"
        addStringOption "federate android", "http://d.android.com/reference"
        addStringOption "federationxml android", "http://doclava.googlecode.com/svn/static/api/android-10.xml"
        addStringOption "federate JDK", "http://download.oracle.com/javase/6/docs/api/index.html?"
        addStringOption "federationxml JDK", "http://doclava.googlecode.com/svn/static/api/openjdk-6.xml"
        addStringOption "templatedir", "${project.docsDir}/${name}/doclava/templates"
        addStringOption "apixml", "${project.docsDir}/${name}/doclava/api-${project.version}.xml"
        addStringOption "since doclava/since/api-1.0.0.xml", "1.0.0"
        addStringOption "apiversion", "${project.version}"
        failOnError false
    }
    // exclude generated files
    exclude '**/BuildConfig.java'
    exclude '**/R.java'
    // exclude internal packages
    exclude '**/internal/**'
    options.addStringOption "apixml", "${project.docsDir}/${name}/doclava/api-${project.version}.xml"
  }
}

Some things I have tried:

• Hardcode the path to the generated R.java file and add to the classpath.

classpath += project.files(android.sourceSets.main.java.srcDirs, variant.javaCompile.classpath.files, android.bootClasspath, ext.R)

This successfully removes the errors so the build succeeds, but the resulting javadoc has empty links to R.*.class in the javadoc.

• Remove the exclude '**/R.java' line from the exclude list along with not including the path to R.java in the classpath.

This successfully removes the errors and the build succeeds, but the resulting javadoc has links to R.*.class files.

It seems the exclude statement is excluding from the classpath and not the javadoc. Any insight into how to generate a javadoc where classes depend on R.java but don't include R.java in the javadoc output would be deeply appreciated.

Answer 1

On Android Studio, go to the following settings (settings can be accessed via File > Settings):

Appearance & Behaviour > Scopes

You should be able to browse your project files here. Now select your files and use the buttons on the far right to include/exclude them to your scope (you can exclude, or not include R.java files and BuildConfig.java files). Make sure the checkbox at the bottom "Share scope" is ticked, and your scope has a memorable name.

Next go to the Javadoc generator dialog (Tools > Generate Javadoc). Select the bottom radio button ("Custom Scope") and then from the menu, select the scope you created earlier. There are other settings you can configure for your Javadocs.

Finally click 'OK', and you should have generated Javadocs.

Hopefully this should solve your problem.