skip to content

What is @MustBeDocumented for, and how does it differ from @Retention and @Target in effect?

level: middleimportance: nice to knowfreq 25%

answer

  1. Docs-only effect
  2. Makes annotation appear in generated API docs (Dokka)
  3. Takes no parameters
  4. Maps to Java @Documented
  5. Does not affect targets or retention

basics

~10 s

@MustBeDocumented marks an annotation as part of an element's public API so documentation tools include it. It changes docs only — not where the annotation can go or how long it's kept.

solid answer

~40 s

`@MustBeDocumented` is a meta-annotation that flags an annotation as belonging to the public API of whatever it is applied to, so documentation generators (such as Dokka, and the Java `@Documented` equivalent) render it in the generated API docs. It takes no parameters. It is purely a documentation concern: unlike `@Target`, it does not restrict where the annotation can be applied, and unlike `@Retention`, it does not affect whether the annotation survives to the binary or to runtime reflection. You'd add it to semantically meaningful annotations like `@Deprecated`-style markers or framework annotations whose presence is part of the contract. It maps to Java's `@Documented` for interop.

go deeper

for a junior

Knows it makes the annotation show up in generated documentation.

for a middle

Distinguishes its docs-only effect from @Target (where) and @Retention (how long), and knows it takes no args.

for a senior

Maps it to Java @Documented and gives sound guidance on which annotations deserve it (contract-bearing markers).

for a principal

Frames it within public-API governance — which framework annotations should be visible to API consumers and why doc visibility matters for stability signalling.

## Purpose `@MustBeDocumented` (in `kotlin.annotation`) marks an annotation as **part of the public API** of the element it annotates. Documentation tools — Kotlin's **Dokka**, or anything honoring the Java `@Documented` contract — will then include the annotation in the generated reference for that class/function/property. It takes **no arguments**: ```kotlin @MustBeDocumented @Target(AnnotationTarget.FUNCTION) annotation class Experimental ``` Now when `@Experimental fun beta()` is documented, the docs show `@Experimental` on `beta`, signalling its status to readers of the API. ## How it differs from the other meta-annotations | Meta-annotation | What it controls | Affects compiler enforcement? | Affects reflection? | Affects docs? | |---|---|---|---|---| | `@Target` | *Where* the annotation may be used | Yes (illegal targets are errors) | Indirectly | No | | `@Retention` | *How long* it is kept (SOURCE/BINARY/RUNTIME) | Yes | Yes (RUNTIME needed to read) | No | | `@MustBeDocumented` | Whether it appears in generated docs | No | No | **Yes** | | `@Repeatable` | Whether it can repeat on one target | Yes | Affects how you read multiples | No | So `@MustBeDocumented` is the only one whose sole observable effect is on **generated documentation**. It does not gate usage, does not change retention, and does not change runtime visibility. ## Java interop It corresponds to Java's `java.lang.annotation.@Documented`. The Kotlin compiler maps between them so a Kotlin annotation marked `@MustBeDocumented` is treated as documented when consumed from Java tooling, and vice versa. ## When to use it Use it for annotations whose **presence is part of the contract** a consumer should see — stability markers, role markers, security/authorization markers — rather than internal implementation-only annotations.

  • Does @MustBeDocumented change runtime visibility of the annotation?
    No. Runtime visibility is governed solely by @Retention (you need RUNTIME). @MustBeDocumented only influences documentation generation.
  • What is its Java equivalent?
    java.lang.annotation.@Documented. The Kotlin compiler maps between the two for interop.

Like marking a footnote 'print this in the published edition' — it only changes what shows up in the docs.

saying these in an interview costs you the question

  • Claiming @MustBeDocumented makes the annotation readable via reflection
  • Thinking it restricts where the annotation can be applied
  • Believing it takes parameters
  • Confusing it with @Retention(RUNTIME)
  • Saying it has no Java counterpart

context

resolving links…