How configure Gradle to generate Javadoc for Testing classes (JUnit)

Help/Discuss
1

Hello

I have the following in my gradle.build file:

apply plugin: 'java'
apply plugin: 'maven'
apply plugin: 'eclipse'
apply plugin: 'war'

version = '1.0.0'
sourceCompatibility = '1.8'
targetCompatibility = '1.8'

repositories {
	//mavenLocal()
	mavenCentral()
}

ext {
		
	//Logging
	slf4jVersion = '1.7.10'
	logbackVersion = '1.1.2'
	
        ….
		
	//Testing
	junitVersion = '4.+'
}

dependencies {	
	
	
	testCompile "junit:junit:$junitVersion"
	
        …
}


war {
	//version=''
    baseName = 'something'
}

When I execute the javadoc command I can see the JavaDoc generated but only for the src/main/java. That’s expected.

But I did realize there is no javadoc for the test classes.

I want to know if is viable the following:

  • What extra settings is need it to include for the generated javadoc the src/test/java?
  • Therefore it means src/main/java + src/test/java together.
  • I want to know if Gradle is able to create or generate a different or external javadoc but only dedicated for testing classes
  • Therefore it means two differents javadocs, one for src/main/java and other for src/test/java

Thanks

2

As you pointed out, to generate javadoc with production code and test code is add test classes information to source and classpath property of javadoc.

plugins {
  id 'java'
}
javadoc {
  classpath += sourceSets.test.compileClasspath
  source += sourceSets.test.allJava
}

And if you create custom javadoc task for unit tests, it won’t be merged to the javadoc for production code. And unfortunately there is no default task to merge javadocs.

// creating javadoc task for test code
task testJavadoc(type: Javadoc) {
  source = sourceSets.test.allJava
  classpath = sourceSets.test.compileClasspath
  // if not changed the destinationDir, the javadoc for production code is overridden.
  destinationDir = file("${buildDir}/docs/testjavadoc")
}

So, as you concluded…

  1. Combine production source codes and test codes in one javadoc task(like former sample).
  2. Have to javadocs(like later sample).
3

Hello

Thanks by the reply.

I have tried both solutions, below my experience.

For the first approach I did realize that is mandatory declare

plugins {
  id 'java'
}
javadoc {
  classpath += sourceSets.test.compileClasspath
  source += sourceSets.test.allJava
}

In the beginning of the gradle.build file, otherwise I get the following error message:

> startup failed:
  build file '/.…some path…./build.gradle': 9: only buildscript {} and other plugins {} script blocks are allowed before plugins {} blocks, no other statements are allowed
  
  See http://gradle.org/docs/2.2.1/userguide/plugins.html#sec:plugins_block for information on the plugins {} block
  
   @ line 9, column 1.
     plugins {
     ^
  
  1 error

(1) Pls confirm that is normal

Ok, when is declared in the beginning I can execute the javadoc command.

The command generates the expected, both main and test classes together in one javadoc.

But always ends the command throwing this exception

Process 'command '/Library/Java/JavaVirtualMachines/jdk1.8.0_60.jdk/Contents/Home/bin/javadoc'' finished with non-zero exit value 1
Could not execute build using Gradle distribution 'https://services.gradle.org/distributions/gradle-2.2.1-bin.zip'.

I don’t know what is wrong.

About the second approach

// creating javadoc task for test code
task testJavadoc(type: Javadoc) {
  source = sourceSets.test.allJava
  classpath = sourceSets.test.compileClasspath
  // if not changed the destinationDir, the javadoc for production code is overridden.
  destinationDir = file("${buildDir}/docs/testjavadoc")
}

Does not work, never is generated the testjavadoc folder. Something is missing there

Thanks by your support.

4

For the first error, my aim is to show you java plugin is applied to your project. If you have already applied java plugin, you don’t have to add the plugins{} block.

On the second case, does the task testJavadoc end with success? Or ends with Failure? Please let me know the build results.

5

Hello

And again thanks by your support.

For the first approach, therefore in this way:

apply plugin: 'java'

javadoc {
  classpath += sourceSets.test.compileClasspath
  source += sourceSets.test.allJava
}

The code works. The exception message has been removed because due error syntax about how I wrote the javadoc. All has been removed.

Therefore first approach works fine!

For the second, no error message

[sts] -----------------------------------------------------
[sts] Starting Gradle build for the following tasks: 
[sts]      javadoc
[sts] -----------------------------------------------------
:compileJava UP-TO-DATE
:compileGroovy UP-TO-DATE
:processResources UP-TO-DATE
:classes UP-TO-DATE
:javadoc

BUILD SUCCESSFUL

Total time: 3.609 secs
[sts] -----------------------------------------------------
[sts] Build finished succesfully!
[sts] Time taken: 0 min, 3 sec
[sts] ------

But the expected directory does not exist. I am assuming something is missing.

6

If 2nd task works correctly, a directory build/docs/testjavadoc will be generated.

The sample project is available at my repository. So you can try testing.

7

Yes, It works fine… I am very tired

Through the IDE for the Gradle Tasks View when I write javadoc only appears that.
Do not appears testJavadoc.

When I write the command test now I can see the expected testJavadoc command and I can execute it.

Therefore approach two works how is expected

Thanks by share your repository

Just curious, you have both taks

javadoc {
    classpath += sourceSets.test.compileClasspath
    source += sourceSets.test.allJava
}

task testJavadoc(type: Javadoc) {
    source = sourceSets.test.allJava
    classpath = sourceSets.test.compileClasspath
    destinationDir = file("${buildDir}/docs/testjavadoc")
    println (title == null? '<null>' : title)
}

Only for demonstration purposes, Am I correct? So I can assume that I can remove the first. Am I correct?

Thanks a lot by all your valuable and kind support!

8

You can remove the first javadoc{} block. Then

  • javadoc task is for generate javadoc for production code.
  • testJavadoc task is for generate javadoc for test code.