Dokka Javadoc

Dokka Javadoc (Javadoc)

Kotlin 프로젝트의 문서를 Java처럼 보이게 만들고 싶을 때가 있어요. Dokka의 Javadoc 출력 형식이 바로 그런 경우에 쓰는 것이에요. 어떤 특징이 있고, 어떻게 생성하는지 살펴볼게요.

출처: Javadoc

본문

이 가이드는 Dokka Gradle 플러그인(DGP) v2 모드에 해당해요. DGP v1 모드는 더 이상 지원되지 않으니, v1에서 v2로 올리려면 Migration guide를 따라가면 돼요.

Dokka의 Javadoc 출력 형식은 Java의 Javadoc HTML 형식과 비슷하게 생겼어요.

Javadoc 도구가 만든 HTML 페이지를 시각적으로 흉내 내려고 하지만, 직접 그 도구의 구현이거나 정확한 복사본은 아니에요.

모든 Kotlin 코드와 시그니처는 Java의 관점에서 본 모습으로 렌더링돼요. 이건 우리의 Kotlin as Java Dokka 플러그인 덕분인데, 이 형식에서는 기본으로 번들되어 적용돼요.

Javadoc 출력 형식은 Dokka 플러그인으로 구현되어 있고 Dokka 팀이 유지 관리해요. 오픈소스라서 소스 코드는 GitHub에서 볼 수 있어요.

Javadoc 문서 생성하기

Dokka는 멀티 프로젝트 빌드나 Kotlin Multiplatform 프로젝트에서는 Javadoc 형식을 지원하지 않아요.

Gradle용 Dokka 플러그인에는 Javadoc 출력 형식이 포함되어 있어요. 프로젝트의 build.gradle.kts 파일에 있는 plugins {} 블록에서 해당 플러그인 ID를 적용하면 돼요:

plugins {
    id("org.jetbrains.dokka-javadoc") version "2.2.0"
}

플러그인을 적용하고 나면 다음 태스크를 실행할 수 있어요:

dokkaGenerate — 적용된 플러그인에 기반한 모든 사용 가능한 형식으로 문서를 생성해요.
dokkaGeneratePublicationJavadoc — Javadoc 형식으로만 문서를 생성해요.

javadoc.jar 파일은 따로 생성할 수 있어요. 자세한 내용은 Building javadoc.jar를 참고해요.

Maven용 Dokka 플러그인에는 Javadoc 출력 형식이 내장되어 있어요. 다음 goal을 사용해서 문서를 생성하면 돼요:

Goal	Description
dokka:javadoc	Javadoc 형식으로 문서 생성
dokka:javadocJar	Javadoc 형식의 문서를 담은 javadoc.jar 파일 생성

Javadoc 출력 형식이 Dokka 플러그인이기 때문에, 플러그인의 JAR 파일을 다운로드해야 해요.

Javadoc 출력 형식에는 추가 JAR 파일로 제공해야 할 의존성이 두 개 있어요:

커맨드 라인 옵션으로 실행할 때는:

java -jar dokka-cli-2.2.0.jar \
     -pluginsClasspath "./dokka-base-2.2.0.jar;...;./javadoc-plugin-2.2.0.jar" \
     ...

JSON 설정으로 실행할 때는:

{
  ...
  "pluginsClasspath": [
    "./dokka-base-2.2.0.jar",
    "...",
    "./kotlin-as-java-plugin-2.2.0.jar",
    "./korte-jvm-3.3.0.jar",
    "./javadoc-plugin-2.2.0.jar"
  ],
  ...
}

더 자세한 내용은 CLI 러너 문서의 Other output formats에서 확인할 수 있어요.

더 알아보기

Maven에서 Javadoc 산출물을 만드는 방법은 Dokka Maven 문서를 참고해요.
Dokka 플러그인을 적용하고 확장하는 법은 Dokka plugins에서 배워요.