DEV Community

あかやん
あかやん

Posted on

Kotlin用のJavadoc(dokka)でドキュメント化する要素を可視性で制御する

はじめに

Kotlinではソースコードのドキュメント(Javadoc)化にdokkaを使用する事が多いと思います。
dokkaは、デフォルトでprivateも含めてすべての可視性の要素がドキュメントとして出力されてしまい、ライブラリを公開した際などに不要な要素などが混じってしまう可能性があります。
その際、ドキュメント化する要素を可視性修飾子により決定することで、publicな要素のみをドキュメントとして公開できてドキュメントの可読性が向上します。その方法について紹介します。

(前提) Kotlinの可視性修飾子

https://dogwood008.github.io/kotlin-web-site-ja/docs/reference/visibility-modifiers.html
private, protected, internal, publicの4つがあります。Javaではinternalという可視性は存在しません。これは同じモジュール内から参照可能となる可視性で、ライブラリを作成するときに非常に重宝しました(Javaのpackage protectとほぼ同等かと思います)

(前提) dokkaの記述方法

build.gradle.kts

plugins {
    id("org.jetbrains.dokka") version "1.6.21"
}

apply(plugin="org.jetbrains.dokka")

buildscript {
    repositories {
        jcenter()
    }
    dependencies {
        classpath("org.jetbrains.dokka:dokka-gradle-plugin:1.6.21")
    }
}
Enter fullscreen mode Exit fullscreen mode

以上を記述した上で、以下のコマンドを実行します

gradle dokkaHtml
Enter fullscreen mode Exit fullscreen mode

するとbuild/dokka/配下にindex.htmlなどが作成されるかと思います。

dokkaの出力を可視性修飾子により制御する方法

build.gradle.kts

import org.jetbrains.dokka.gradle.DokkaTask

tasks.withType<DokkaTask>().configureEach {
    dokkaSourceSets {
        configureEach {
          documentedVisibilities.set(listOf(
            org.jetbrains.dokka.DokkaConfiguration.Visibility.PUBLIC,
            org.jetbrains.dokka.DokkaConfiguration.Visibility.PROTECTED
          ))
        }
    }
}
Enter fullscreen mode Exit fullscreen mode

上記の例ではDokkaTaskconfigureEachで出力する可視性として(Visibility.PUBLIC, Visibility.PROTECTED)を設定しました。
あとは、先程と同じように

gradle dokkaHtml
Enter fullscreen mode Exit fullscreen mode

でpublic及びprotectedのみの要素のドキュメントを生成することが可能です。

このDokkaTaskconfigureEach内には、他にもいろいろな項目が設定可能となっています。詳しくはこちらをご覧ください。
https://kotlin.github.io/dokka/1.6.21/user_guide/gradle/usage/

Discussion (0)