26

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.

jdONeill
  • 443
  • 6
  • 10
  • I have tried to override the error with the `options.addStringOption "warning", "110"` which did not work, then recompiled the doclava jar to hardcode in the value of `WARNING` for error code `110` which did not work either. Seems the error is not coming from doclava as there is no error code so overwriting is not working. `error: Can resolve symbol *R.class` where a doclava error would be `error 101: Unresolved link`. – jdONeill Jan 03 '16 at 00:50
  • So what is the goal exactly? What would you like the R references to link to? Because best case i can think of is if you include the R file the you coverage goew down and you cant test R anyways. Are you just wanting the R file references to resolve to the int value the represent? Include think ase which case why? You will never ever get the R references to show the actual value resolved @ runtime. So what is the benefit of include get them? – JBirdVegas Jan 23 '16 at 08:21
  • Excluding them causes the build task to fail. Including them satisfies the references, but includes them in the Javadoc output. The goal is to satisfy the references for the build task(s), but leave the R and BuildConfig classes out of the generated Javadocs. There should be no references to R or BuildConfig within the .jar -embedded Javadocs, nor in the generated Javadoc HTML. – jneander Jan 25 '16 at 16:40
  • Are you using Android Studio? To be clear, are you just trying to generate Javadocs without generating the `R.java` ones, but also including `R.java` in the code, as the APIs depend on it? – Farbod Salamat-Zadeh Jan 27 '16 at 20:25
  • This is a build issue using Gradle whereby build servers do not have Android Studio, or any IDE, installed. – jdONeill Jan 28 '16 at 01:46
  • Does this set-up produce valid links for tags like`{@link android.app.Activity#onResume()} ` and attributes like `@attr ref android.R.styleable#View_foreground`? – Petrakeas Feb 15 '16 at 20:12
  • No, the issue there is I can't find the federated xml for Android API ref. The http://doclava.googlecode.com/svn/static/api/android-10.xml link is no longer valid. – jdONeill Aug 09 '16 at 17:56
  • @jdONeill did you find a solution for this ? :) – Matej Špilár Mar 21 '17 at 08:50
  • No I still have not found a solution for this unfortunately. – jdONeill Apr 18 '17 at 21:56

2 Answers2

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.

Farbod Salamat-Zadeh
  • 19,687
  • 20
  • 75
  • 125
0

I suspect you are trying to exclude R.java because the auto-generated javadoc in that class doesn't conform to doclint. So you are seeing a bunch of errors and warnings like:

R.java:530: error: unknown tag: colgroup
     * <colgroup align="left" />
       ^

What about removing the exclude '**/R.java' and suppressing any errors generated by R.java instead?

Using this as a basis, and then looking at Xdoclint documentation, you should be able suppress R.java errors by adding: 

options.addStringOption('Xdoclint:none R.java', '-quiet')

I have tested this and it removes the R.java errors. You'll still see them print to console, but it won't count in the final error numbers.

tir38
  • 9,810
  • 10
  • 64
  • 107