Dokka in Android :: Documentation engine for Kotlin

WindSekirun (wind.seo)·2022년 4월 26일

이 글은 기존 운영했던 WordPress 블로그인 PyxisPub: Development Life (pyxispub.uzuki.live) 에서 가져온 글 입니다. 모든 글을 가져오지는 않으며, 작성 시점과 현재 시점에는 차이가 많이 존재합니다.

작성 시점: 2017-11-09

Dokka 는 Java의 JavaDoc와 동일한 기능을 수행하는 문서 엔진이며 Java의 JavaDoc 문법과 Kotlin 의 KDoc 문법을 완벽히 지원, html 이나 markdown 등의 포맷으로 생성할 수 있게 해준다.

여기서는 안드로이드 프로젝트에서 어떤 방식으로 문서를 생성하는지 정리하려고 한다.

준비

dependencies {
        classpath 'com.android.tools.build:gradle:3.0.0'
        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
        classpath "org.jetbrains.dokka:dokka-android-gradle-plugin:0.9.15"
        // NOTE: Do not place your application dependencies here; they belong
        // in the individual module build.gradle files
}

apply plugin: 'org.jetbrains.dokka-android'

com.android.library 와 kotlin-android 의 밑에 적으면 된다.

Dokka 설정

dokka {
    moduleName = 'RichUtils'
    outputFormat = 'html'
    outputDirectory = "$projectDir/docs"
    sourceDirs = files('src/main/java')
    skipEmptyPackages = true
    linkMapping {
        dir = "src/main/java"
        url = "https://github.com/WindSekirun/RichUtilsKt/tree/master/RichUtils/src/main/java"
        suffix = "#L"
    }
}

현재 RichUtils 에서 사용하고 있는 Dokka 설정 코드이다.

각각 설명해보면,

moduleName: 모듈 이름, 문서에 표시되는 프로젝트 이름이다.
outputFormat: html, javadoc, html-as-java, markdown, gfm, jekyll, kotlin-website* 종류로 나뉜다.
- html: 기본 포맷, 매우 간결한 html 포맷
- javadoc: JavaDoc 레이아웃 형태
- html-as-java : html 이나 자바 문법
- markdown: Markdown 구조로 작성
- gfm: Github Flavored markdown
- jekyll: Jekyll compatible markdown
- Kotlin-website* - kotlinlang.org 에 사용되는 내부 포맷
outputDirectory: 결과를 저장할 곳이다. $projectDir 이면 dokka 가 설정되어 있는 build.gradle 의 폴더명이다. 즉, RichUtilsKt/RichUtils/docs 이다.
sourceDirs: 코드 파일이 저장된 곳이다.
skipEmptyPackages: 패키지가 비어있을 때 스킵할지 안할지 결정한다.
linkMapping: dir 에 있는 코드 파일들과 Git에 올라가있는 코드 파일을 매핑해서 링크를 만들어준다.

그 외 다른 옵션들도 있다.

jdkVersion: JDK 의 어떤 버전을 링크할지 적는다.
cacheDefault: package-list 캐싱 기능에서 캐시가 저장될 곳을 적는다. 기본으로는 $USER_HOME/.cache/dokka 이다.
includeNonPublic : public 가 아닌 메서드나 필드를 포함할지 안할지 정한다.
skipDeprecated: Deprecated 된 것을 스킵할지 안할지 결정한다.
reportNotDocumented: 문서화되지 않았을 경우 경고를 내보냅니다.
noStdlibLink: kotlin-stdlib 로 링크를 만들지 않는다.

실행

Windows

gradlew dokka

Mac / Linux

./gradlew dokka

문법

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

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

param 파라미터 설명. param[name] 설명 식으로 적어도 된다.
return: 반환되는 값에 대한 설명
constructor: 클래스의 주 생성자에 대한 설명
property : 속성에 대한 설명
receiver: Extension function 의 receiver 에 대한 설명
throws, exception 예외에 대한 설명. Kotlin 에는 예외검사가 없으므로 가능한 모든 예외가 문서화 해야 된다는 기대는 없지만 이 태그가 사용자한테 유용한 정보를 제공할 수 있다고 판단될 때 사용할 수 있다.
sample: sample 코드에 대한 연결
see: See Also 문단에 연결될 특정 클래스나 메서드를 적는다.
author: 작성자
since: 이 요소가 소개된 소프트웨어의 시점
suppress: 모듈의 공식 api 는 아니지만 외부에서 볼 수 있어야 할 때 작성합니다.