javadoc.gradle

//It seems the gradle javadoc task works file by file and as such disable some features of javadoc tool
//such as link to packages, https://groups.google.com/d/msg/gradle-dev/R83dy_6PHMc/bgw0cUTMFAAJ

def java8DocsUrl = 'https://docs.oracle.com/javase/8/docs/api/'
def packageListUrl = "$java8DocsUrl/package-list"
def java8DocsDir = "$buildDir/javase-8-docs"

// Temporary workaround for https://github.com/mockito/mockito/issues/2765
// For Java 8, download the `package-list` as `element-list`
task downloadJava8ElementList(type: Download) {
    src packageListUrl
    // Since the JavaDoc output is generated in `$buildDir/javadoc`, specify a different location for this task
    dest "$java8DocsDir/element-list"
    overwrite true
}

// Temporary workaround for https://github.com/mockito/mockito/issues/2765
// For Java 9+, download the `package-list` as-is
task downloadJava9PlusPackageList(type: Download, dependsOn: downloadJava8ElementList) {
    src packageListUrl
    // Since the JavaDoc output is generated in `$buildDir/javadoc`, specify a different location for this task
    dest java8DocsDir
    overwrite true
}

javadoc {
    description "Creates javadoc html for Mockito API."
    dependsOn downloadJava9PlusPackageList

    // For more details on the format
    // see https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javadoc.html

    source = sourceSets.main.allJava
    destinationDir = file("$buildDir/javadoc")
    title = "Mockito ${project.version} API"

    // The way *gradle* javadoc task works and due to *gradle exclusion* the log output triggers javadoc warning and
    // errors on internal classes that are not found, non-exhaustive list :
    //
    // * import org.mockito.internal.Internal <- error: package org.mockito.internal does not exists
    // * import org.mockito.internal.Internal.util <- error: static import only from classes and interfaces
    // * class Public extends Internal <- cannot find symbol
    // * warning - Tag @linkplain: reference not found: org.mockito.internal.Internal internal stuff
    // * warning - Tag @link: reference not found: org.mockito.stubbing
    //
    // While there's errors the javadoc is still generated without those symbols or links ;
    // for this reason the javadoc output is suppressed and can be reactivated with --info option.
    exclude 'org/mockito/internal'

    options.docTitle = """<h1><a href="org/mockito/Mockito.html">Click to see examples</a>. Mockito ${project.version} API.</h1>"""
    options.windowTitle = "Mockito ${project.version} API"
    options.group("Main package", ["org.mockito"])
    options.memberLevel = JavadocMemberLevel.PROTECTED
    options.outputLevel = JavadocOutputLevel.QUIET
    options.charSet = 'UTF-8'
    options.encoding = 'UTF-8'
    options.docEncoding = 'UTF-8'
    options.use = true
    options.splitIndex = true
    options.noDeprecated = false
    options.noDeprecatedList = false
    options.noIndex = false
    options.noNavBar = false
    options.noTree = false
    options.links('https://junit.org/junit4/javadoc/4.12/')
    options.linksOffline(java8DocsUrl, java8DocsDir)
    options.bottom("""
        <script type="text/javascript" src="{@docRoot}/js/jdk6-project-version-insert.min.js"></script>
        <script type="text/javascript" src="{@docRoot}/js/jquery-1.7.min.js"></script>
        <script type="text/javascript" src="{@docRoot}/js/highlight-8.6-java/highlight.pack.js"></script>

        <link rel="stylesheet" type="text/css" href="{@docRoot}/js/highlight-8.6-java/styles/obsidian.css"/>
        <script type="text/javascript" src="{@docRoot}/js/index.js" async defer></script>
    """.replaceAll(/\r|\n|[ ]{8}/, ""))
    options.stylesheetFile rootProject.file("src/javadoc/stylesheet.css")
    options.addStringOption('Xwerror', '-quiet')
    options.addBooleanOption('-allow-script-in-comments', true)

    doLast {
        copy {
            from "src/javadoc"
            into "$buildDir/javadoc"
        }
    }
}