How to automatically generate diff between API versions?

Question

The Android Open Source regularly releases a list of API differences between API levels. Here are some examples from developer.android.com:

Difference between API Level 18 and 19

Difference between API Level 14 and 15

This looks like it was somehow automatically generated.

I would like to use a similar tool so I can track differences between API versions of my own source code.

What tool can do this for me?

Answer 1

They use JDiff, spring also uses it on their documentations.

If you are using gradle you can use this file as reference on how to make use of JDiff to generate API difference reports automatically:
https://github.com/Netflix/governator/blob/master/jdiff.gradle

/*
 * Copyright 2015 Netflix, Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
plugins {
    id 'org.ajoberstar.github-pages' version '1.4.2'
}
/**
 * Generate a JDiff report between a newer version and an older version.
 *
 * Usage:
 *  gradle -PjDiff.olderVersion=2.1312.0 [-PjDiff.newerVersion=2.1716.0] generateJDiffReport
 *
 * View generated report at:
 *  build/reports/jDiff/${olderVersion}-to-${newerVersion}/changes.html
 */
task generateJDiffReport(dependsOn: '_jDiff_cloneOldVersion') {
    description = "Generates a JDiff report"
    group = "Documentation"

    final jDiffHome = "${rootProject.rootDir}/buildSrc/lib/jdiff-1.1.1/"

    ant.taskdef(
        name: 'jDiff',
        classname: 'jdiff.JDiffAntTask',
        classpath: "${jDiffHome}/antjdiff.jar")

    doLast {
        final olderVersion = project.getProperty('jDiff.olderVersion')
        final olderVersionRoot = new File("${rootProject.buildDir}/jDiff/${rootProject.name}-${olderVersion}")

        if (olderVersion == null)
            throw new IllegalArgumentException(
                'Set `jDiff.olderVersion` property to indicate older of the two versions being compared')

        final newerVersion = project.hasProperty('jDiff.newerVersion') ? project.getProperty('jDiff.newerVersion') : rootProject.version
        final newerVersionRoot = rootProject.rootDir

        final outputDir = "${rootProject.buildDir}/reports/jDiff/${olderVersion}-to-${newerVersion}"
        mkdir(outputDir)

        ant.metaClass.jDiff_getSrcDirSets = { root ->
            root.eachDirMatch({ dir ->
                new File("${dir}/src/main/java").exists()
            }) { dir ->
                dirset(dir: "${dir}/src/main/java")
            }
        }

        ant.property(name: "JDIFF_HOME", value: jDiffHome)
        ant.jDiff(
            destdir: outputDir,
            verbose: 'off',
            stats: 'on',
            docchanges: 'off',
            source: '1.8') {
            old(name: "${rootProject.name}-${olderVersion}") {
                jDiff_getSrcDirSets(olderVersionRoot)
            }

            'new'(name: "${rootProject.name}-${newerVersion}") {
                jDiff_getSrcDirSets(newerVersionRoot)
            }
        }
    }
}
import org.ajoberstar.grgit.Grgit
task _jDiff_cloneOldVersion << {
    final olderVersion = project.getProperty('jDiff.olderVersion')
    final olderVersionRoot = new File("${rootProject.buildDir}/jDiff/${rootProject.name}-${olderVersion}")

    final newerVersionRoot = rootProject.rootDir

    if (!olderVersionRoot.isDirectory()) {
        Grgit.clone(
            uri: "file://${newerVersionRoot.path}/.git",
            dir: olderVersionRoot.path,
            refToCheckout: "refs/tags/v${olderVersion}")
    }
}