How to generate javadoc for android library when it has dependencies which are also aar libraries?

Question

I have android library project which depends on other android library projects. I need to generate javadoc for library but it fails because gradle puts to javadoc classpath path to .aar locations but javadoc expects .jar files.

simplified gradle file:

android {
    compileSdkVersion 23
    buildToolsVersion "23.0.2"

    configurations {
        javadocDeps
    }

    defaultConfig {
        minSdkVersion 7
        targetSdkVersion 23
        versionCode 1
        versionName "0.1.0"
    }
}

dependencies {
    compile 'com.android.support:support-v4:23.2.0'
    compile 'com.android.support:appcompat-v7:23.2.0'
    compile 'com.nineoldandroids:library:2.4.0'
    compile 'com.annimon:stream:1.0.7'
    javadocDeps 'com.android.support:support-annotations:23.2.0'
    javadocDeps 'com.nineoldandroids:library:2.4.0'
    javadocDeps 'com.android.support:support-v4:23.2.0'
}

task sourcesJar(type: Jar) {
    from android.sourceSets.main.java.srcDirs
    classifier = 'sources'
}    

task javadoc(type: Javadoc, dependsOn: explodeAars) {
    source = android.sourceSets.main.java.srcDirs
    classpath += project.files(android.getBootClasspath().join(File.pathSeparator))
    classpath += configurations.javadocDeps
}

task javadocJar(type: Jar, dependsOn: javadoc) {
    classifier = 'javadoc'
    from javadoc.destinationDir
}

artifacts {
    archives javadocJar
    archives sourcesJar
}

3 solutions possible:

1) somehow to add to the classpath path classes.jar from every aar library it depends build/intermidiates/exploded-aar/library/version/jars/classes.jar I don't know how to include these paths in javadoc task.

2) manually unpack classes.jar from aar file and add them to classpath of javadoc task

3) very dirty hack - hardcoded paths to library - but I think this is so WRONG.

How to achieve 1 or 2 with gradle dsl?

Answer 1

I managed to automate the solution of Guillaume Perrot by extracting the classes.jar contained in each AAR file, and adding it to the classpath of the javadoc task.

It seems to work for AAR dependencies and AAR modules on Android Studio 2.3 and Gradle 3.3

import java.nio.file.Files
import java.nio.file.Paths
import java.io.FileOutputStream
import java.util.zip.ZipFile

task javadoc(type: Javadoc) {
    source = android.sourceSets.main.java.srcDirs
    classpath += configurations.compile
    classpath += configurations.provided

    afterEvaluate {
        // Wait after evaluation to add the android classpath
        // to avoid "buildToolsVersion is not specified" error
        classpath += files(android.getBootClasspath())

        // Process AAR dependencies
        def aarDependencies = classpath.filter { it.name.endsWith('.aar') }
        classpath -= aarDependencies
        aarDependencies.each { aar ->
            // Extract classes.jar from the AAR dependency, and add it to the javadoc classpath
            def outputPath = "$buildDir/tmp/aarJar/${aar.name.replace('.aar', '.jar')}"
            classpath += files(outputPath)

            // Use a task so the actual extraction only happens before the javadoc task is run
            dependsOn task(name: "extract ${aar.name}").doLast {
                extractEntry(aar, 'classes.jar', outputPath)
            }
        }
    }
}

// Utility method to extract only one entry in a zip file
private def extractEntry(archive, entryPath, outputPath) {
    if (!archive.exists()) {
        throw new GradleException("archive $archive not found")
    }

    def zip = new ZipFile(archive)
    zip.entries().each {
        if (it.name == entryPath) {
            def path = Paths.get(outputPath)
            if (!Files.exists(path)) {
                Files.createDirectories(path.getParent())
                Files.copy(zip.getInputStream(it), path)
            }
        }
    }
    zip.close()
}

Answer 2

The solution from @rve is now broken on Android Studio 2.3 / Gradle 3.3 as the exploded-aar no longer exists (with no alternative inside the build directory).

If the aar you depend on is not a module in your project, you will need first to extract the classes.jar before referencing it in the classpath (basically re-create intermediates/exploded-aar manually).

If the aar you depend on is just another module in your project you can also make your javadoc task depends on the compile task of that module and reference the intermediates/classes/release of that module (if you make javadoc depends on assembleRelease for example). An example of that workaround: https://github.com/Microsoft/mobile-center-sdk-android/pull/345/files

I really wish someone comes up with a better solution though.