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.

Screen Shot 2017-05-30 at 5.15.32 PM.png

 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:
Screen Shot 2017-05-30 at 5.24.40 PM.png

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.
Screen Shot 2017-05-30 at 5.48.58 PM.png

 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.
Screen Shot 2017-05-30 at 5.29.49 PM.png
Then when you navigate to a package.html file you’ll see this warning.
Screen Shot 2017-05-30 at 5.31.48 PM.png
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.
Screen Shot 2017-05-30 at 6.01.50 PM.png

 Questions I still have

 
8
Kudos
 
8
Kudos

Now read this

Dealing with TimeZones in Java without Joda Time

I’ve begun working on a java SDK for nexmo’s API. Thanks to the wonders of timezones I had a crappy time (the 24 hour cold I currently have didn’t help). Mark works in the UK and I work on East Coast time. Only because of our team’s... Continue →