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:
UNDOCUMENTED_PUBLIC_API: a placeholder KDoc instead of@IntentionallyUndocumented, because documentation doesn't break any user.SUBCLASS_OPT_IN_WITHOUT_MARKERS: a markerless@SubclassOptInRequireddoesn't restrict any subclass, so the task replaces it with@IntentionallyOpen. The class stays open to everyone.DSL_MARKER_NOOP_TYPE_POSITION: no exemption annotation exists. The task reports the diagnostic as a warning. Move or remove the marker by hand.
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:
exemptExistingApiexempts a check set toERRORand leaves a check set toWARNING. A check set toNONEinapiWatchdogdoesn't record anything. - The three always-error checks are off, because
FOR_BACKWARDS_COMPATIBILITYisn't a reason for them:EXEMPTION_WITHOUT_EXPLANATION: only the author of the exemption can write its reason.PUBLIC_TYPE_WITH_INTERNAL_API: the internal type has to leave the signature.PUBLIC_TYPE_FROM_NON_TRANSITIVE_DEPENDENCY: declare the dependency withapiin the build script. This doesn't break any consumer.
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.