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

Cropo·2022년 3월 22일

시작

이직을 하거나 프로젝트에 합류할때면 문서화의 중요함을 매번 느낍니다. 여러 개발자가 함께 개발하는만큼 서로가 바로 이해하지 못하는 코드들을 언어로서 풀어서 쉽게 파악할 수 있게 도움을 줍니다. 가장 흔하게 접할 수 있는 문서로는 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 { ... }
}

블록태그

Block tag	Description
@param name	class, function 등에 사용되는 변수에 대한 설명 작성. 다음과 같이 공백과 대괄호를 사용한 2가지 표현 방식이 있다. `ex) @param name description. @param[name] description.`
@return	함수의 반환값에 대한 설명 작성
@constructor	class의 기본 생성자에 대한 설명 작성
@receiver	kotlin extention 함수의 receiver에 대한 설명 작성
@property name	class 생성자에 있는 properties에 대한 설명 작성
@throws class, @exception class	메소드에 의해 발생 가능한 예외에 대한 설명 작성. 모든 예외에 대한 설명을 작성하는 것이 아닌 유용한 정보만 필요에 의해 작성.
@sample identifier	요소의 사용방법에 대한 예시 코드를 작성.
@see identifier	원하는 클래스 혹은 메소드에 대한 링크를 작성.
@author	문서의 작성자를 명시.
@since	문서가 작성된 시점의 버전을 작성.
@suppress	해당 요소를 생성된 문서에서 제외 시키고 싶은 경우 작성.

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 페이지에서 확인 가능합니다.