[Kotlin] KDoc으로 코틀린 코드 문서화하기 (feat. Dokka)

시작

이직을 하거나 프로젝트에 합류할때면 문서화의 중요함을 매번 느낍니다. 여러 개발자가 함께 개발하는만큼 서로가 바로 이해하지 못하는 코드들을 언어로서 풀어서 쉽게 파악할 수 있게 도움을 줍니다. 가장 흔하게 접할 수 있는 문서로는 API 문서가 있습니다.
본 글에서는 KDoc, Dokka를 통해 안드로이드 코드에 문서를 작성하는 방법에 대해 다룰 예정입니다.

KDoc

KDoc은 Kotlin 코드의 문서화를 위한 언어이고 JavaDoc과 동일하다고 볼 수 있습니다.
JavaDoc의 여러 문법들과 흡사하지만 큰 차이점은 JavaDoc은 HTML을 사용하고 KDoc은 마크다운을 사용합니다.

문법

JavaDoc과 동일하게 KDoc은 /** 로 시작하여 */로 끝납니다.
통상적으로 문서의 첫번째 단락은 요약이고 두번째 단락부터는 자세한 설명입니다.
모든 블록태그는 줄의 앞부분에 위치하고 @로 시작합니다.

다음은 KDoc의 예시 코드입니다.

/**
 * 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 { ... }
}

블록태그

KDoc에서는 @deprecated 태그를 지원하지 않습니다. 대신 @Deprecated 어노테이션을사용을 권장합니다.

Dokka

KDoc을 통해 코드에 문서를 작성하였다면 Dokka를 통해 html 등의 형태로 파일로 내보내기가 가능합니다.

참고 링크의 KDoc, 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

dokkaHtml gradle task를 통해 outputDirectory에서 지정한 폴더에 문서 파일이 생성된 것을 확인할 수 있습니다.

참고 링크

코틀린 공식 사이트
Dokka 공식 문서 사이트
Dokka Github 사이트
KDoc, Dokka 예제 코드