【Kotlin】@MustBeDocumentedアノテーションは何に使う？

@MustBeDocumented

ざっくり概要

This meta-annotation determines that an annotation is a part of public API and therefore should be included in the generated documentation for the element to which the annotation is applied.

つまり、@MustBeDocumentedを適用したannotation classを公開APIとみなし、
そのannotation classを適用した要素(クラスや関数）のドキュメントにannotation classの情報を含めますよ〜
という宣言に用いるみたいです（ややこしい）

Javaでいうところの@Documentedですね

参考：@Documented アノテーションの意味

ざっくり使ってみる

以下のように、@MustBeDocumentedを適用したアノテーションと
適用していないアノテーションクラスを作成し、それぞれを通常のクラスに付与します

TestClass.kt

@MustBeDocumented
annotation class A_Annotation()

annotation class B_Annotation()

@A_Annotation
@B_Annotation
class TestClass()

〜

Kotlinのドキュメントの生成にはdokkaというJetBrains製のライブラリを使います
公式のガイド通りにビルド設定をし・・・

buildscript {
    repositories {
        jcenter()
    }

    dependencies {
        classpath "org.jetbrains.dokka:dokka-gradle-plugin:0.9.14"
    }
}

apply plugin: 'org.jetbrains.dokka'

dokka {
    outputFormat = 'html' 
    outputDirectory = "$buildDir/html"
}

えいや！

> ./gradlew dokka

〜

すると、
以下のようなドキュメントが生成されました

@MustBeDocumentedを適用したA_Annotationクラスのみドキュメントに出力されてますね

余談

ちなみにdokka0.9.14で"Javadoc"を出力すると、アノテーションは表示されませんでした

dokka {
    outputFormat = 'javadoc' 
    outputDirectory = "$buildDir/javadoc"
}