[Kotlin Tutorial] Documenting Kotlin code

[Kotlin Tutorial] Documenting Kotlin code

출처 : Kotlin in action

1. Writing Kotlin documentation comments

-

Java 의 Javadoc 만들 때와 비슷하다.

Kotlin 의 것은 KDoc 이라 부른다.

-

KDoc 은 /** 로 시작하고 tag 는 마찬가지로 @ 로 시작한다.

Javadoc 과의 가장 큰 차이가 있다면 HTML 대신 Markdown 을 사용한다는 것이다.

/**

 * Calculates the sum of two numbers, [a] and [b]

 */

fun sum(a: Int, b: Int) = a+b

정의를 참조하려면 [ ] 안에 이름을 넣어주면 된다.

cf) Markdown 은 text-to-HTML conversion tool 이다.

-

Javadoc 에서 제공하는 tag 외에 추가적인 tag 들을 제공한다.

예를 들면 @receiver 인데, extension function, property 의 receiver 를 명시하는 것이다.

아래 link 에 full-list 가 있다.

http://kotlinlang.org/docs/reference/kotlin-doc.html 

-

@sample tag 는 API 사용방법을 명시하는 데 사용하면 된다.

-

반대로 Javadoc 에서는 제공하지만 KDoc 에서는 지원하지 않는 것도 있다.

@deprecated 는 @Deprecated annotation 으로 치환되었다.

@inheritdoc 은 지원하지 않는다. 기본적으로 모든 comment 는 기본적으로 상속된다.

@code, @literal, @link 는 그에 상응하는 Markdown format 으로 전환된다.

2. Generating API documentation

-

Kotlin 의 document 생성 tool 은 Dokka 라고 불린다.

Kotlin 처럼 Dokka 는 Java/Kotlin 모두를 support 한다.

Java code 에서는 Javadoc 을 읽고, Kotlin 코드에서는 KDoc 을 읽어서 전체 API set 에 대해 문서를 생성한다.

-

Dokka 는 여러 가지 format 의 output 을 지원한다.

plain HTML, Javadoc-style HTML, Markdown

-

Command line 으로 Dokka 를 실행시킬 수도 있고, Build script 안에 내용을 추가할 수도 있다.

다음 글 : [Kotlin Tutorial] The Kotlin ecosystem

@, @code, @deprecated, @inheritdoc, @link, @literal, @receiver, @sample, api 사용법 명시, build script, command line, COMMENT, dokka, extension function, extension property, generate api doc, generating api documentation, HTML, java kotlin, javadoc, javadoc-style html, kdoc, Kotlin, kotlin @link, kotlin basics, kotlin comment, kotlin tutorial, markdown, markdown format, plain html, receiver, TAG, text-to-html conversion tool, Writing Kotlin documentation comments, [], 기본 상속, 주석, 코틀린, 코틀린 강좌, 코틀린 기초 강좌