CODEWITHSUNDEEP
javaandroideclipsejavadocbuildconfig
Michael Levy
Michael Levy

Reputation: 13297

How can I document or exclude the generated BuildConfig class in my documentation?

Apparently, since Android SDK 17, builds generate an automatic class called BuildConfig and add it to my package. http://android-developers.blogspot.com/2012/03/updated-sdk-tools-and-adt-revision-17.html says:

Added a feature that allows you to run some code only in debug mode. Builds now generate a class called BuildConfig containing a DEBUG constant that is automatically set according to your build type. You can check the (BuildConfig.DEBUG) constant in your code to run debug-only functions such as outputting debug logs.

Since this source file is generated, I can't see how to add JavaDoc comments to it. Is there an easy way to exclude this class from my package documentation? or is there an easy way to add some comments to this class? Since this class is added to my package, I can't simply exclude the package from the docs.

I'm using Eclipse Indigo on Windows and the standard Doclet.

Upvotes: 4

Views: 1362

Answers (2)

slhck
slhck

Reputation: 38740

Disabling the generation of the BuildConfig class itself was not an option for me, as I depend on it in production builds as well. Here is the basic Gradle task:

tasks.register('javadoc', Javadoc) {
    title = "My Docs v${android.defaultConfig.versionName}"
    failOnError true
    options.memberLevel = JavadocMemberLevel.PUBLIC
    source = android.sourceSets.main.java.srcDirs +
                 fileTree(dir: "${buildDir}/generated/source/buildConfig/release")
    destinationDir = file("${project.rootDir}/docs/")
    classpath += files("${android.sdkDirectory}/platforms/${android.compileSdkVersion}/android.jar")

    // packages to exclude from the docs
    excludes = [
        "com/example/foobar"
    ]

    // exclude '**/BuildConfig.java'
    // --> does not work because we get a build failure

    options.addStringOption("-source-path", android.sourceSets.main.java.srcDirs.join(":"))
}

Javadoc does not seem to allow you to exclude the BuildConfig class: you get errors about the class not being found. Hence, the only ugly workaround seems to be to use the @hidden tag in the class docs.

Since you cannot control the generation of the file itself, I am using the following helper script to build the docs, modifying the class in-place before running the right Gradle task:

#!/usr/bin/env bash
#
# Helper to build the docs.
# We need to modify the BuildConfig.java file in-place to hide it from
# Javadoc, because excluding it will break the build.

set -e

BUILD_CONFIG_FILE=./foobar/build/generated/source/buildConfig/release/com/example/foobar/BuildConfig.java

if [ ! -f "$BUILD_CONFIG_FILE" ]; then
  echo "ERROR: $BUILD_CONFIG_FILE not found!"
  echo "Did you run ./gradlew foobar:assembleRelease?"
  exit 1
fi

# add a @hidden tag to "public final class BuildConfig {"
perl -pi -e 's/public final class BuildConfig {/\/** \@hidden *\/\npublic final class BuildConfig {/' $BUILD_CONFIG_FILE
perl -pi -e 's/.*Field from default config.*/\/** Field from default config\n\@hidden *\//' $BUILD_CONFIG_FILE

./gradlew javadoc

Of course, replace foobar with the right project path.

Upvotes: 0

yorkw
yorkw

Reputation: 41126

To remove BuildConfig.java, simply untick your project/gen folder in the javadoc export wizard. Note that this also remove the R.java from exported javadoc:

enter image description here

Upvotes: 3

Related Questions