Gradle Build Customizations

The following snippets show various ways to customize the default Gradle build.

JavaDoc Generation for API (Exported) Packages

The built-in 'javadoc' task in Gradle works fine and generates documentation under the generated/docs directory. However by default it generates javadocs for all packages, including private packages which are not API. The following snippet allows us to generate javadocs only for exported packages, which are assumed to be public API.

Note that this script assumes the Export-Package statement only contains a simple list of package names. If wildcards, directives or other features are used then the processing of the statement will have to be more complicated.

To use, first insert the following into build.gradle at the project root:

subprojects {
  if (project.hasProperty('bnd')) {
    apply from: cnf.file('gradle/javadoc.gradle')
  }
}

Now create the file cnf/gradle/javadoc.gradle as follows:

/*
 * Generate JavaDocs only for exported packages
 */
ext.javadocSpecs = bnd('Export-Package', project.name)

/*
 * Allow projects to set the JavaDoc page title with a 'javadoc.title' field in their
 * bnd.bnd file. Otherwise the project name is used
 */
ext.javadocTitle = bnd('javadoc.title', project.name)

javadoc {
	source bnd.allSrcDirs
	javadocSpecs.split(/\s*,\s*/).each {
		include it.replace('.','/')+'/*.java'
	}
	configure(options) {
		docTitle = javadocTitle
		windowTitle = javadocTitle
		memberLevel = JavadocMemberLevel.PROTECTED
		charSet = 'UTF-8'
		encoding = 'UTF-8'
		docEncoding = 'UTF-8'
		use = true
		splitIndex = true
		noDeprecated = false
		noDeprecatedList = false
		noIndex = false
		noNavBar = false
		noTree = false
		links('http://docs.oracle.com/javase/8/docs/api/')
	}
	/* Turn off javadoc 8 overly pedantic lint checking */
	if (JavaVersion.current().isJava8Compatible()) {
		options.addStringOption('Xdoclint:none', '-quiet') 
	}
	doFirst {
		project.delete(destinationDir)
		logger.info "Title    : ${options.windowTitle}"
		logger.info "Packages : ${javadocSpecs}"
		logger.info "Destdir  : ${destinationDir}"
	}
}