Gradle, Javadoc and Android documentation

Question

I'm now using Gradle for all my projects, and even for javadoc generation.

android.libraryVariants.all { variant ->

    task("generate${variant.name}Javadoc", type: Javadoc) {
        title = "$name $version API"
        source = variant.javaCompile.source
        ext.androidJar = "${android.plugin.sdkDirectory}/platforms/${android.compileSdkVersion}/android.jar"
        ext.googlePlayServicesJar = "${android.plugin.sdkDirectory}/extras/google/google_play_services/libproject/google-play-services_lib/libs/google-play-services.jar"
        classpath = files(variant.javaCompile.classpath.files, ext.androidJar, ext.googlePlayServicesJar)
        options.links("http://docs.oracle.com/javase/7/docs/api/");
        options.links("http://d.android.com/reference/");
        //options.linksOffline("http://d.android.com/reference", "${android.plugin.sdkDirectory}/docs/reference");
        exclude '**/BuildConfig.java'
        exclude '**/R.java'
    }

}

With that code I got everything working, except one thing: regular Android API objects like Activity, Bitmap etc. Java's links are working fine.

The final generated documentation does not link to http://d.android.com/reference. I tried both options.links() and options.linksOffline() without success.

EDIT

Thanks to @ejb, the problem was that you cannot provide multiple options.links() at the same time. So I used both options.links() for Java's documentation and options.linksOffline() for Android's documentation:

options {
    links("http://docs.oracle.com/javase/7/docs/api/");
    linksOffline("http://d.android.com/reference", "${android.plugin.sdkDirectory}/docs/reference");
    //stylesheetFile = new File(projectDir, "stylesheet.css");
}

Answer 1

I was able to successfully link to http://d.android.com/reference using the following snippet which is functionally exactly what you have (as far as I can tell).

 android.libraryVariants.all { variant -> 
   task("generate${variant.name.capitalize()}Javadoc", type: Javadoc) {
     // title = ''
     // description = ''
     source = variant.javaCompile.source 
     classpath = files(variant.javaCompile.classpath.files, project.android.getBootClasspath()) 
     options { 
       links "http://docs.oracle.com/javase/7/docs/api/" 
       linksOffline "http://d.android.com/reference","${android.sdkDirectory}/docs/reference" 
     } 
     exclude '**/BuildConfig.java' 
     exclude '**/R.java' 
   } 
 }

So there is something else amiss here.

You have to build the javadoc offline, as it doesn't seem the package-list is available on the path of the web service. Maybe double check that you actually have the docs loaded locally, and make sure there is a package-list in the /[android-sdk]/docs/reference directory.

If you still can't figure it out, perhaps you could post output.

Another thing you might check is the ./build/tmp/[taskname]/javadoc.options, the head of said file should show the appropriate options carefully set. Things to check for would include the proper inclusion of the android.jar in the -classpath and the presence of linksOffline with expected arguments: -linksoffline extDocURL packageListLoc

javadoc.options should have both options with only the respective arguments:

-linksoffline 'http://d.android.come/reference' '[sdkDir]/docs/reference'
-links 'http://docs.oracle.com/javase/7/docs/api/' 

EDIT: android.getBootClasspath() is nicer, thanks to P-chan.

Answer 2

For Android Gradle plugin 1.1.2+ (com.android.tools.build:gradle:1.1.+)

libraryVariants - does not work anymore

use:

task javadoc(type: Javadoc) {
    source = android.sourceSets.main.java.srcDirs
    classpath += project.files(android.getBootClasspath().join(File.pathSeparator))
    destinationDir = file("../javadoc/")
    failOnError false
}

destinationDir = file("../javadoc/") - locate javadocs at root of project directory (in this way jenkins javadoc plugin could find it and show in special Document panel)

failOnError false - for suppress warnings that can cause fail build on jenkins

---

Alternative for Gradle JavaDocs

Doxygen - cross reference documentation tool.

could be run from UI or terminal: http://www.doxygen.nl/manual/doxygen_usage.html

---

Generating javadoc available throw java tool: 'javadoc'

run from command line:

javadoc -d docs -sourcepath app/src/main/java -subpackages com

docs - destination folder