Undocumented public API
| Diagnostic | UNDOCUMENTED_PUBLIC_API |
| Default severity | Warning |
| Gradle property | undocumentedPublicApi |
| Exemption | @IntentionallyUndocumented |
What it reports
A declaration in the public API without its own KDoc. The check tests for a KDoc block, not its content.
public class Store
Rationale
Document the behavior callers can rely on, including limits and failure conditions. An undocumented use can become a compatibility constraint when users depend on it.
See Kotlin API guidelines on documenting your API for more details.
Don't
public class Cache(private val capacity: Int) {public fun get(key: String): String? = store[key]}
Do
/** An in-memory string cache. */public class Cache(private val capacity: Int) {/*** Returns the cached value for [key],* or null when the key doesn't have a cached value.*/public fun get(key: String): String? = store[key]}
Notes
- A member property of a class, an interface, or an object isn't reported by default, because the
check doesn't read the
@propertyand@paramtags of the class KDoc. Class properties turns the property part of the check on. - Overrides and
actualdeclarations aren't reported. - The check skips default-named companion objects and checks their members and named companions.
- Enum entries, primary constructors, and compiler-generated members aren't reported.
- Plain
//and/* ... */comments don't count as KDoc. @PublishedApi internaldeclarations and declarations inside those classes aren't reported.
Exemption
If this is intended, apply @IntentionallyUndocumented to the declaration.
// No example here, because I couldn't find a valid case when an API// shouldn't be documented 🤷
The annotation exempts only that declaration.
The exemptExistingApi task adds placeholder KDoc instead of this annotation.
It does this only when the check is set to WatchdogSeverity.ERROR.
Replace each placeholder with the declaration's contract.
Configuration
apiWatchdog {undocumentedPublicApi = WatchdogSeverity.WARNING}
For a direct compiler call:
-P plugin:org.jetbrains.kotlinx.library.api.watchdog:diagnosticSeverity=UNDOCUMENTED_PUBLIC_API:warning
Class properties
reportUndocumentedClassProperties is false by default: the check skips every member property
of a class, an interface, and an object, and reports a top-level property. Set it to true when
each property must carry its own KDoc:
apiWatchdog {reportUndocumentedClassProperties = true}
For a direct compiler call:
-P plugin:org.jetbrains.kotlinx.library.api.watchdog:reportUndocumentedClassProperties=true