June 1, 2017

Using Doclava and Gradle to exclude classes from your generated Javadocs

At Nexmo I help out with the Java and Android client libraries. Recently I generated Javadocs for one of our Android client libraries. Usually, Android Studio makes this super easy. It’s as simple as using the “Generate JavaDoc” under the “Tools” menu. But I wouldn’t be writing a blog post if the problem I had to solve was so easy.

Our team wanted to exclude certain classes from the generated java docs. The engineers I was working with had already started that by using the @hide annotation at the top of the classes we wanted excluded. But the problem is when you use Android Studio’s built in Javadoc generation tool, you’ll find that it doesn’t respect @hide! So what to do?

The solution I found is to use Doclava (the original repo can be found on Google Code). Though the repo hasn’t been updated in a while, it still works.

There aren’t a lot of instructions out there how to integrate this into your Android Studio project so here’s how I did it.

In your library’s build.gradle file, add the following:

//build.gradle

configurations {
    doclava
}

dependencies {
  ...
  doclava 'com.google.doclava:doclava:1.0.6'
}

task generateJavadoc(type: Javadoc, dependsOn: project.configurations.doclava) {
    failOnError = true
    title = null
    source = android.sourceSets.main.java.srcDirs
    options.doclet = "com.google.doclava.Doclava"
    options.docletpath = configurations.doclava.files.asType(List)
    classpath += 
    project.files(android.getBootClasspath().join(File.pathSeparator))
    destinationDir = file("../javadocs/")
}

Now you can run the generateJavadoc task from Gradle. If you don’t have Gradle in your command line you can use the Gradle pane in Android studio.

Troubleshooting #

After running the gradle task, an empty folder was created with no docs in it #

This might happen if failOnError = false is set in your gradle task. I recommend you set failOnError = true so that you can see what error prevented the javaDoc from being generated.

Where can I see the errors? #

Here:

After you click on Gradle Console you’ll see something like this. It’s helpful to Run with --stacktrace or one of the other options.

javadoc: error - Illegal package name: “…package.html” #

Doclava doesn’t like package.html. Instead it prefers package-info.java You could convert your old package.html files to package-info.java by hand, Or you can also use Android Studio to automate it. Just open preferences for Android Studio and make sure this box is checked.

Then when you navigate to a package.html file you’ll see this warning.

Clicking the convert button will automatically convert the package-info.java to package-info.java

After making changes to the gradle task, the task still doesn’t execute correctly. #

Make sure you sync your gradle files before you run the gradle task. If you see this warning: you haven’t synced yet.

Questions I still have #

Why do I need to include title = null in my gradle task? I’ve tried removing that line or replacing it with title = "Javadoc" and the task fails.
Can I include a navbar in my generated docs? For an example of what I mean look at the difference between the Javadocs for Retrofit generated without Doclava and the Javadocs for this fork of Volley generated with Doclava. Javadocs without Doclava have this awesome Navbar and this “All Classes” link. How can I get that in my Doclava Javadocs?

Kudos