[Kotlin] KDoc 주석이란?

마냥 기능을 작동시키는 코드만 짤 수는 없다. 필요하다면 어떤 클래스, 함수가 무슨 일을 하고 왜 이걸 만들었는지에 대한 주석을 써야 할 수 있다.

주석에 대해 찾다가 이 글까지 본 사람이라면 알겠지만, 코틀린의 주석은 3종류 있다.

 

1. 한 줄 주석(Line comment)
2. 블록 주석(Block comment)
3. KDoc 주석

 

이 중에서 KDoc 주석에 대해 정리하려고 한다. 먼저 자바를 공부했던 사람이라면 자바독 주석을 알 텐데, KDoc 주석이 바로 자바독 주석이다. 코틀린이라 앞에 'K'가 붙은 걸 빼면 모든 게 자바독 주석과 일치한다.

하지만 자바를 공부한 적 없고 코틀린부터 시작했다면 아래 공식문서부터 보자.

 

https://kotlinlang.org/docs/kotlin-doc.html

Document Kotlin code: KDoc | Kotlin

코틀린 코드를 문서화하는 데 사용되는 언어를 KDoc이라고 한다. 본질적으로 KDoc은 자바독의 블록 태그 구문과 인라인 마크업을 위한 마크다운을 결합한다
자바독과 마찬가지로 KDoc 주석은 "/**"로 시작하고 "*/"로 끝난다. 주석의 모든 줄은 별표로 시작할 수 있으며 주석 내용의 일부로 간주되지 않는다. 관례적으로 첫 단락은 요약 설명이고 다음 텍스트는 자세한 설명이다. 모든 블록 태그는 새 줄에서 시작하고 @로 시작한다. 아래는 KDoc을 사용해 문서화된 클래스 예시다

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

@param : 함수의 타입 매개변수, 클래스, 프로퍼티를 문서화한다. 설명과 매개변수명을 더 잘 구분하기 위해 원한다면 매개변수명을 대괄호로 묶을 수 있다. 따라서 아래의 두 구문은 동일하다
- @param name description / @param[name] description

@return : 함수의 리턴값을 문서화
@constructor : 클래스의 기본 생성자를 문서화
@receiver : 확장 함수의 리시버 변수를 문서화
@property_name : 특정 이름을 가진 클래스의 프로퍼티를 문서화. 이 태그는 주 생성자에서 선언된 프로퍼티를 문서화하는 데 사용할 수 있다
@throws_class, @exception_class : 메서드에 의해 발생할 수 있는 예외를 문서화. 코틀린에는 확인된(checked) 예외가 없으므로 가능한 모든 예외가 문서화될 거라는 기대도 없다. 하지만 클래스 사용자에게 유용한 정보를 제공하려면 이 태그를 사용한다
@sample : 요소를 사용할 수 있는 방법의 예시를 보여주기 위해 어떤 정규화된 이름을 가진 함수 본문을 현재 주석에 포함한다
@see : 문서의 참고 항목 블록에 지정된 클래스 or 메서드의 링크를 추가
@author : 문서의 작성자 명시
@since : 문서화하는 요소가 도입된 소프트웨어 버전을 지정
@suppress : 생성된 문서에서 요소를 제외한다. 공식 API의 일부는 아니지만 외부에서 볼 수 있어야 하는 요소에 사용할 수 있다

 

공식문서에서 말하는 KDoc 주석에서 사용할 수 있는 문법은 위와 같다.

아래는 미디엄에서 가져온 또 다른 KDoc 주석 예시다.

 

/**
 * Calculator class which has a add method
 *
 * @author by Ali Shobeyri
 * @see <a href="https://google.com">google link</a>
 *
 * @property battery is the percentage of how much charges the calculator has
 *
 */
class Calculator(val battery : Float) {
    /**
     * @param value_1 is first input
     * @param value_2 is second input
     *
     * @return this function return [value_1] + [value_2]
     *
     * @throws Exception if the battery is 0%
     */
    fun add(value_1: Int, value_2: Int): Int{
        if(battery > 0) return value_1 + value_2
        else throw Exception("No Charge")
    }
}

 

위 코드를 IDE에 붙여넣고, 주황색 책 아이콘을 클릭하면 아래처럼 표시된다.

 

 

그러나 직접 "/**"를 입력하고 엔터 친 다음, 저것들을 모두 작성하기는 번거롭다.

그래서 완전히는 아니지만 번거로움을 어느 정도 해소할 수 있는 인텔리제이 플러그인이 있다. kdoc-generator라는 플러그인이다.

 

 

설치 후 재시작할 필요도 없고, 함수 시그니처를 모두 작성한 다음 KDoc 주석을 작성하면 플러그인이 자동으로 매개변수의 개수만큼 @param을 만들어 준다.

 

 

참고한 사이트)

 

https://medium.com/@drflakelorenzgerman/documentation-with-kdoc-for-kotlin-android-a93c99dfe74

Documentation with KDoc for Kotlin/Android

 

https://dev-jewon.tistory.com/21

Kotlin 코드 문서화를 위한 주석 작성 방법