How to fail gradle build on Javadoc warnings

Question

I'm using Java 7 (though compiliing using 1.6) to compile classes, and the javadocs. I've eliminated all javadoc warnings which come up, but the idea is to have the build fail if there are any javadoc warnings.

Using Java 8, this is the default behaviour. BUT, it's also a lot more strict when it comes to warnings (we don't want warnings if a method doesn't list all @params, or @returns). Plus, I don't see the company moving to 8 anytime soon, so it's a moot point.

I was hoping there was some easy flag to set to have gradle fail if there are warnings (there's only failonError). What I was thinking, was to scrape the console output of the javadoc process. If that output contains WARNINGS, then I know there are warnings, and the build should fail.

Here's my javadoc block in my build.gradle:

task gendocs(type: Javadoc) {
options.stylesheetFile = new File("./assets/doc_style.css")
options.windowTitle = "OurTitle"
options.memberLevel = JavadocMemberLevel.PROTECTED
options.author = true
options.linksOffline('http://d.android.com/reference', System.getenv("ANDROID_HOME") + '/docs/reference')
String v = "${SEMVER}"
version = v.replace("_", '.')
destinationDir = new File("${BUNDLE_FOLDER}/docs/api")
source = sourceSets.main.allJava
classpath += configurations.compile
}

So, if there isn't an easier way to do this, how do I check the console output of javadoc to scrape it?

Answer 1

There is a non-standard hidden javadoc option -Xwerror available on all supported Java releases. Thus you could simply do something like this:

if (JavaVersion.current().isJava8Compatible()) {
    tasks.withType(Javadoc) {
        // The '-quiet' as second argument is actually a hack,
        // since the one paramater addStringOption doesn't seem to
        // work, we extra add '-quiet', which is added anyway by
        // gradle. See https://github.com/gradle/gradle/issues/2354
        // See JDK-8200363 (https://bugs.openjdk.java.net/browse/JDK-8200363)
        // for information about the -Xwerror option.
        options.addStringOption('Xwerror', '-quiet')
    }
}

A feature request for an official '-Werror' for javadoc is tracked as JDK-8200363. This feature is now available in JDK 15+ as -Werror, -Xwerror also works as an alias.

Answer 2

note: i've totally replaced my original answer, because i've found a better one - which is not that ugly:

import org.gradle.logging.internal.OutputEvent
import org.gradle.logging.internal.OutputEventListener

        task("javadocCheck",type:Javadoc){
            // regular javadoc task configuration

            def outputEvents = []
            def listener=new OutputEventListener(){
                    void onOutput(OutputEvent event){
                        outputEvents << event
                    }
                };
            doFirst {
                getLogging().addOutputEventListener(listener)
            }
            doLast {
                getLogging().removeOutputEventListener(listener)
                outputEvents.each { e ->
                    if(e.toString() =~ " warning: "){
                        throw new GradleException("You have some javadoc warnings, please fix them!");
                    }
                }
            }
        }

Answer 3

task.getLogging() is now deprecated and LoggingManagerInternal#addOutputEventListener() got removed.

Here is a solution that should work with Gradle >2.14.

    import org.gradle.api.logging.StandardOutputListener

    task("javadocCheck",type: Javadoc) {
        // regular javadoc task configuration

        def capturedOutput = []
        def listener = { capturedOutput << it } as StandardOutputListener
        doFirst {
            logging.addStandardErrorListener(listener)
            logging.addStandardOutputListener(listener)
        }
        doLast {
            logging.removeStandardOutputListener(listener)
            logging.removeStandardErrorListener(listener)
            capturedOutput.each { e ->
                if(e.toString() =~ " warning: ") {
                    throw new GradleException("You have some javadoc warnings, please fix them!");
                }
            }
        }
    }

Answer 4

I just wanted to follow this up since the accepted answer did not work in my environment using JDK 11 and Gradle 5. Here's one I used to address compilation warnings:

import org.gradle.internal.logging.*
import org.gradle.internal.logging.events.*


compileJava {
    def outputEvents = []
    def listener=new OutputEventListener() {
        void onOutput(OutputEvent event) {
            outputEvents << event
        }
    };

    doFirst {
        gradle.services.get(LoggingOutputInternal).addOutputEventListener(listener)
    }

    doLast {
        gradle.services.get(LoggingOutputInternal).removeOutputEventListener(listener)
        outputEvents.each { e ->
            if (e.toString() =~ " warning: ") {
                throw new GradleException("\n\n\tERROR: You have compilation warnings!\n\n")
            }
        }
    }
}