부록 B. 코틀린 코드 문서화
KOTLIN IN ACTION 부록 B를 요약한 내용입니다.
코틀린 선언에 사용하는 문서화 주석의 형식은 자바독(JavaDoc)과 비슷하며, 케이독(KDoc)이라 불린다. 자바독처럼 케이독 주석도 /**으로 시작하며, 특정 선언을 문서화할 때는 @로 시작하는 태그를 사용한다. 자바독과 케이독의 가장 큰 차이는 HTML이 아니라 마크다운을 문서 작성 형식으로 사용한다는 점이다.
/**
* Performs a complicated operation.
*
* @param remote If true, executes operation remotely
* @return The result of executing the operation
* @throws IOException if remote connnection fails
* @sample com.mycompany.SomethingTest.simple
*/
fun somethingComplicated(remote: Boolean): ComplicatedResult { ... }
각 태그의 문법은 자바독과 같다. @Receiver 태그는 확장 함수나 프로퍼티의 수신 객체를 문서화하는 태그다. 지원하는 모든 태그 목록은 http://kotlinlang.org/docs/reference/kotlin-doc.html에서 볼 수 있다.
케이독은 다음과 같은 일부 자바독 태그를 지원하지 않는다.
- @deprecated 태그는 없어 지고 @Deprecated 애노테이션이 태그 역할도 대신한다.
- @inheritdoc을 지원하지 않는다. 코틀린에서는 문서화 주석이 오버라이딩한 상위 클래스 멤버의 주석을 언제나 자동 상속한다.
- @code, @literal, @link을 지원하지 않는다. 같은 역할을 하는 마크다운 기능을 사용해야 한다.
코틀린 문서 생성 도구는 도카(Dokka)다. 코틀린과 마찬가지로 도카도 자바와 코틀린을 함께 사용하는 프로젝트를 완전히 지원한다. 도카는 자바 코드에 있는 자바 독 주석과 코틀린 코드에 있는 케이독 주석을 읽을 수 있고, 코드 작성에 사용한 언어와 관계없이 모듈 전체를 다루는 문서를 생성할 수 있다. 도카는 일반 HTML, 자바독 형식의 HTML, 마크다운 등의 여러 출력 형식을 지원한다.
Last modified 2yr ago