Android Library AAR and Javadoc

As an Android developer, I’m used to ask Android Studio/Intellij Idea for documentation constantly. I have even replaced the shortcut: now, it’s F1, the old-fashion help key. When I want to know about a method or a class, I hit F1 and the JavaDoc shows up: smooth. How does this works? Story time!

The Catapush user

Could you point me to the new method when a method gets deprecated. It’s easier for me to replace the old API this way.

And I was like: WTF!? I hate when this happens to me and that’s why I’m taking the time to save the hassle to Catapush users!!! The method is @Deprecated and there is a nice “Please, use this other method” in the Javadoc. I see it! It’s here! Why is he telling me there is no JavaDoc!? And then it hit me…

ME: Are you saying that AAR files don’t contain JavaDoc?

HardReality: Yes, Ivan, little naive Android developer

Most of the time, during your Android development, the documentation shows up because you are using open source libraries. Our IDE retrieves the sources.jar file under the hood and shows the JavaDoc directly from the source code.

Catapush is closed source (for now 😉 ) so we are only distributing the AAR file using Jitpack. AAR means no JavaDoc in the library. No sources.jar means no JavaDoc retrieved from the source code.

HTML JavaDoc

As first step, I tried to create an HTML version of the JavaDoc just for the sake of having it published. With Jitpack, this is a no-brainer. Simply add this to your build.gradle:

task javadoc(type: Javadoc) {
    failOnError false
source = android.sourceSets.main.java.sourceFiles
    classpath += project.files(android.getBootClasspath().join(File.pathSeparator))
    classpath += configurations.compile
}

// build a jar with javadoc
task javadocJar(type: Jar, dependsOn: javadoc) {
    classifier = 'javadoc'
from javadoc.destinationDir
}

artifacts {
    archives javadocJar
}

Push your library to Github, build it with Jitpack and you will have your HTML doc at https://jitpack.io/com/github/USER/REPO/VERSION/javadoc/

Problem solved! No! I find HTML doc unpractical. I want it in my IDE.

The Interface trick

The only way to have doc in the IDE is to distribute it as source code. When you work with closed source libraries, this is not an option, but… you can publish a part of the source code.

I extracted interfaces for every class that is part of the public API of the library and I documented the interfaces, instead of the implementations.

public interface ICatapush {

/**
     * Initializes Catapush
     *
     * @param context  Application Context. Catapush should be initialized in your class that extends Android Application,
     *                 passing <b>this</b> as {@link Context};
     * @param callback You can receive a callback call when the initialization is completed.
     */
void init(@NonNull Context context, @NonNull Callback<Boolean> callback);

/**
 * Starts Catapush. This is the final method of the chain.
 * Be sure to call this after {@link #setAppKey(String)},
 * {@link #setUser(String, String)}, {@link #setPush(Notification)} and {@link #setGcmSenderId(String)}.
 */
void start();
}

Once every interface was documented, I could publish the sources.jar via Jitpack, with a few lines in my build.gradle:

// build a jar with source files
task sourcesJar(type: Jar) {
    from android.sourceSets.main.java.srcDirs
    classifier = 'sources'

include("**/ICatapush.java")
}

artifacts {
    archives sourcesJar
}

Sync, push and build and you are done! Every time you import Catapush in your project, Android Studio/Intellij Idea will retrieve the sources.jar under the hood and, when you ask for documentation, the magic will happen:

Our IDE is smart enough to inherit the Javadoc from the interface when we ask it on the actual implementation.

Conclusions

Extract a few interfaces, add your Javadoc, add a few lines to your Gradle file and you are good to go. Documentation is important for your users and your co-workers: don’t let them down.

I don’t really know why there is no support for documentation in the AAR format and, right now, it doesn’t matter anymore:

Android community, like Nature, always finds a way.