Android Dokka를 통한 KDoc 문서화하기

정리 배경

작성된 코드를 문서처럼 팀에게 공유하고 싶을 때 Swagger처럼 가독성이 좋은 문서를 만들고 싶었습니다. 찾다보니 Android Dokka를 통해 Swagger처럼 문서화(KDoc)가 가능하다는 것을 알 수 있었고 이를 공유하고자 합니다.

 

KDoc란 무엇일까?

Kotlin 문서에서 KDoc를 다음과 같이 소개하고 있습니다.

The language used to document Kotlin code (the equivalent of Java's Javadoc) is called 
KDoc. In essence, KDoc combines Javadoc's syntax for block tags (extended to support Kotlin's specific constructs) and Markdown for inline markup.


Kotlin 코드를 문서화하는 데 사용되는 언어(자바의 Javadoc에 해당)를 KDoc라고 합니다. 본질적으로 KDoc은 Javadoc의 블록 태그 구문(Kotlin의 특정 구조를 지원하도록 확장됨)과 Markdown을 결합하여 인라인 마크업을 수행합니다.

 

KDoc 문법

Javadoc과 마찬가지로 KDoc 주석은 /**로 시작하여 */로 끝납니다. 주석의 모든 행은 주석 내용의 일부로 간주되지 않는 별표로 시작할 수 있습니다.

 

관례에 따라 문서 텍스트의 첫 번째 단락(첫 번째 빈 줄까지 텍스트 블록)은 요소에 대한 요약 설명이고, 다음 텍스트는 자세한 설명입니다.

 

예를 들어 다음과 같은 코드가 있다고 가정합니다.

첫 번째 단락엔 A group of *members* 라는 해당 클래스에 대한 설명이 적혀있습니다.

다음 단락엔 클래스에 대한 자세한 설명이 정리되어 있습니다.마지막 단락엔 각 매개변수, 프로퍼티, 생성자에 대한 설명을 정리합니다.

/**
 * 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로 문서화하게 되면 다음과 같은 문서가 생성됩니다.

전체 파일들에 대한 설명일 땐 첫 줄에 명시된 설명이 표시되며, 세부적으로 들어갔을 때 주석에 명시된 모든 설명들이 보이게 됩니다.

 

KDoc 만드는 방법

1. project의 build gradle에 plugin을 추가해줍니다.

plugins {
    id 'org.jetbrains.dokka' version '1.6.10'
}

 

2. app 모듈에도 플러그인을 추가해줍니다. (문서화하고 싶은 모듈에도 추가해줘야 합니다)

plugins {
    id 'org.jetbrains.dokka'
}

 

3. app 모듈에 dokkaHtml을 설정해줍니다.

android {
   ...
   
    dokkaHtml.configure {
        dokkaSourceSets {
            named("main") {
                noAndroidSdkLink.set(false)
            }
        }
    }
}

 

4. 다음으로 터미널에 명령어를 입력해주면 됩니다.

./gradlew dokkaHtml

 

 

5. 실행이 완료되면 각 모듈의 build 파일 내에서 확인 가능합니다.

 

 

<참고 자료>

https://kotlinlang.org/docs/kotlin-doc.html#kdoc-syntax

https://www.youtube.com/watch?v=i1ljU1WLolc