Skip to main content

Adding the plugin to existing libraries

A change to the public API of a published library breaks its users. So the first run of the Watchdog reports many diagnostics that the author can't act on. The exemptExistingApi task acknowledges every error in one run:

./gradlew exemptExistingApi

Run it on a clean working tree. The task edits the source files.

What the task changes​

The task compiles every compilation except tests and edits every declaration with a diagnostic whose configured severity is ERROR. Each declaration gets the @Intentionally* annotation of its diagnostic with ExemptionReason.FOR_BACKWARDS_COMPATIBILITY. The annotation goes below the KDoc and above the other annotations of the declaration. The task adds the imports.

A diagnostic with the WARNING severity stays in the sources. The console prints the count, and the report lists each one. To exempt a check that is a warning, set it to WatchdogSeverity.ERROR in apiWatchdog for the run. UNDOCUMENTED_PUBLIC_API is a warning by default, so the task doesn't add placeholder KDoc without this setting.

Three diagnostics get a different fix:

The placeholder KDoc satisfies the check until the real documentation replaces it:

/** TODO: Document this declaration */
public class Config

Review the result​

The task writes the API Watchdog report. Its not-applied section lists the diagnostics that need manual attention. The console prints the same list as warnings. In a build with the report aggregation plugin, the task also writes the aggregate reports of the root project.

Review the diff and commit it. The checks then report only the API that you add later. For a new declaration, fix the shape or pick the exemption reason by hand.

A second run doesn't add anything, because an exempted declaration doesn't report a diagnostic.

Collection mode​

exemptExistingApi and generateApiWatchdogReport compile every compilation except tests in collection mode. The report page lists the compilations. When neither task is in the task graph, the compilations run as configured. Collection mode changes three things:

  • A module without explicit API mode compiles with -Xexplicit-api=warning.
  • Every enabled configurable check reports a warning, so the compilation passes. The configured severity still decides the fix: exemptExistingApi exempts a check set to ERROR and leaves a check set to WARNING. A check set to NONE in apiWatchdog doesn't record anything.
  • The three always-error checks are off, because FOR_BACKWARDS_COMPATIBILITY isn't a reason for them:

exemptExistingApi removes a redundant exemption, and generateApiWatchdogReport tags it as redundant. In a multiplatform project, the task removes the copies on the actual declarations with the exemption on the expect declaration.

Any other compilation error still fails the task. Fix unresolved references and syntax errors first. The compilations outside collection mode still report the three always-error checks, so fix them after you commit the generated exemptions.