Skip to main content

Undocumented public API

DiagnosticUNDOCUMENTED_PUBLIC_API
Default severityWarning
Gradle propertyundocumentedPublicApi
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 @property and @param tags of the class KDoc. Class properties turns the property part of the check on.
  • Overrides and actual declarations 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 internal declarations 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​

build.gradle.kts
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:

build.gradle.kts
apiWatchdog {
reportUndocumentedClassProperties = true
}

For a direct compiler call:

-P plugin:org.jetbrains.kotlinx.library.api.watchdog:reportUndocumentedClassProperties=true

See also​