[Kotlin]Kocレコードエラーコード(feat.Dokka)

開始します。

退職やプロジェクトに参加するたびに、ドキュメント化の重要性が感じられます.複数の開発者が一緒に開発する場合、互いに理解していないコードを言語として説明することで、より簡単に理解することができます.最も一般的なドキュメントはAPIドキュメントです.
この文書では、AndroidコードでKocとDokkaを使用してドキュメントを作成する方法について説明します.

KDoc

Kocは、JavaDocと同じKotlinコードを記録するための言語です.
JavaDocの多くの構文と似ていますが、最大の違いは、JavaDocがHTMLを使用し、Kocがタグを使用してダウンロードすることです.

構文

JavaDocと同様、Kocは/**で始まり、*/で終わる.
通常、ドキュメントの最初のセグメントは要約であり、2番目のセグメントは詳細です.
すべてのブロックタグは行の先頭にあり、@で始まる.
以下に、Kocのコード例を示します.

/**
 * A group of *members*.
 *
 * This class has no useful logic; it's just a documentation example.
 *
 * @param T the type of a member in this group.
 * @property name the name of this group.
 * @constructor Creates an empty group.
 */
class Group<T>(val name: String) {
    /**
     * Adds a [member] to this group.
     * @return the new size of the group.
     */
    fun add(member: T): Int { ... }
}

ブロックタグ

Block tagDescription@paramnameclass、functionなどの変数の説明を作成します.スペースと括弧を使用した2つの表現があります.ex) @param name description. @param[name] description.@return関数の戻り値の記述説明@constructorclassのデフォルトジェネレータ記述説明@receiverkotline extendion関数のreceiver記述説明@property nameClassジェネレータの属性作成説明@throws class、@exception classメソッドで発生する可能性のある例外記述説明.すべての例外の説明を作成するのではなく、必要に応じて有用な情報を作成します.@サンプル識別子要素の使用方法のサンプルコードを作成します.@see identifierは、必要なクラスまたはメソッドへのリンクを作成します.@作成者ドキュメントの作成者を指定します.@ドキュメント作成時にバージョンが作成されるためです.@生成されたドキュメントから除外する場合は、suppressを作成します.
Kocは@deprecatedタグをサポートしていません.逆に、@Deprecated操作を推奨します.

Dokka

ドキュメントがKocでコードに作成されている場合は、Dokkaでhtmlなどの形式でファイルにエクスポートできます.
注:リンクのKoc、Dokkaサンプルコードでコード全体を確認できます.
記述されたサンプルコードは、最新バージョン(2022.03.21)に基づいて記述されるため、各バージョンのGradle構文とコードの位置が異なる場合があります.

Dokka pluginの追加

project:build.gradle

plugins {
    id 'com.android.application' version '7.3.0-alpha01' apply false
    id 'com.android.library' version '7.3.0-alpha01' apply false
    id 'org.jetbrains.kotlin.android' version '1.6.10' apply false
    id 'org.jetbrains.dokka' version '1.6.10'
}

app:build.gradle

plugins {
    id 'com.android.application'
    id 'org.jetbrains.kotlin.android'
    id 'org.jetbrains.dokka'
}

android {
	...
}

dokkaHtml {
    dokkaSourceSets {
        outputDirectory.set(new File("$buildDir/dokka"))

        named("main") {
            sourceLink {
                path = "src/main/java"
                lineSuffix = "#L"
            }
            noAndroidSdkLink.set(false)
        }
    }
}

dependencies {
    ...
    
    implementation 'org.jetbrains.dokka:dokka-gradle-plugin:1.6.10'
    dokkaHtmlPlugin("org.jetbrains.dokka:kotlin-as-java-plugin:1.6.10")
}

dokkaの様々なオプションについては、Dokka GithubページとDokka Documentationページを参照してください.

Dokkaドキュメントファイルの作成

./gradlew dokkaHtml

dokka Html gradle taskは、outputDirectoryで指定したフォルダにドキュメントファイルが作成されていることを確認します.

コメントリンク

コトリン公式サイト
Dokka公式ドキュメントサイト
Dokka Githubサイト
KDoc、Dokkaサンプルコード