Kotlin 코드 문서화하기: KDoc

Kotlin 코드 문서화하기: KDoc

Kotlin 코드를 문서화하는 데 사용하는 언어(Java의 Javadoc에 해당하는 것)를 KDoc이라고 불러요. 본질적으로 KDoc은 블록 태그를 위한 Javadoc 구문(Kotlin의 특정 문법을 지원하도록 확장된)과 인라인 마크업을 위한 Markdown을 결합한 것이에요.

출처: Document Kotlin code: KDoc

본문

Kotlin의 문서화 엔진인 Dokka는 KDoc을 이해하고 다양한 형식으로 문서를 생성하는 데 사용할 수 있어요. 자세한 내용은 Dokka 문서를 읽어보세요.

KDoc 구문

Javadoc과 마찬가지로 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 { ... }
}

블록 태그

KDoc은 현재 다음 블록 태그들을 지원해요.

@param name

함수의 값 매개변수 또는 클래스, 프로퍼티, 함수의 타입 매개변수를 문서화해요. 매개변수 이름과 설명을 더 잘 구분하고 싶다면 매개변수 이름을 대괄호로 감쌀 수도 있어요. 따라서 다음 두 구문은 동일해요.

@param name description.
@param[name] description.

@return

함수의 반환 값을 문서화해요.

@constructor

클래스의 주 생성자(primary constructor)를 문서화해요.

@receiver

확장 함수의 수신자(receiver)를 문서화해요.

@property name

지정된 이름을 가진 클래스의 프로퍼티를 문서화해요. 이 태그는 주 생성자에 선언된 프로퍼티를 문서화할 때 사용할 수 있어요. 프로퍼티 정의 바로 앞에 문서 주석을 넣기가 어색한 경우가 많거든요.

@throws class, @exception class

메서드가 던질 수 있는 예외를 문서화해요. Kotlin에는 체크 예외(checked exception)가 없으므로 모든 가능한 예외를 문서화할 것으로 기대되지도 않아요. 하지만 이 태그가 클래스 사용자에게 유용한 정보를 제공한다면 여전히 사용할 수 있어요.

@sample identifier

지정된 정규화된 이름(qualified name)을 가진 함수의 본문을 현재 요소의 문서에 삽입해서, 요소를 어떻게 사용할 수 있는지에 대한 예시를 보여줘요.

@see identifier

지정된 클래스나 메서드에 대한 링크를 문서의 See also 블록에 추가해요.

@author

문서화되는 요소의 저자를 지정해요.

@since

문서화되는 요소가 도입된 소프트웨어 버전을 지정해요.

@suppress

요소를 생성된 문서에서 제외해요. 모듈의 공식 API에 포함되지는 않지만 외부에서 보이긴 해야 하는 요소에 사용할 수 있어요.

KDoc은 @deprecated 태그를 지원하지 않아요. 대신 @Deprecated 애너테이션을 사용하세요.

인라인 마크업

인라인 마크업을 위해 KDoc은 일반 Markdown 구문을 사용하는데, 코드의 다른 요소를 연결하기 위한 축약 구문을 지원하도록 확장되어 있어요.

요소 링크

다른 요소(클래스, 메서드, 프로퍼티, 또는 매개변수)에 연결하려면 그 이름을 대괄호 안에 넣으면 돼요.

Use the method [foo] for this purpose.

링크에 사용자 정의 라벨을 지정하고 싶다면 요소 링크 앞에 대괄호 한 쌍을 추가하면 돼요.

Use [this method][foo] for this purpose.

요소 링크에는 정규화된 이름도 사용할 수 있어요. Javadoc과 달리, 정규화된 이름은 메서드 이름 앞에서도 항상 점 문자로 구성 요소를 분리한다는 점에 주의하세요.

Use [kotlin.reflect.KClass.properties] to enumerate the properties of the class.

요소 링크의 이름은 문서화되는 요소 내부에서 그 이름을 사용한 것과 동일한 규칙으로 해석돼요. 특히 현재 파일에서 이름을 가져왔다면(import), KDoc 주석에서 사용할 때 전체 이름을 적을 필요가 없다는 뜻이에요.

참고로 KDoc에는 링크에서 오버로드된 멤버를 해석할 수 있는 구문이 없어요. Kotlin의 문서 생성 도구는 함수의 모든 오버로드에 대한 문서를 같은 페이지에 넣기 때문에, 특정 오버로드된 함수를 식별하는 것은 링크가 동작하는 데 필요하지 않아요.

외부 링크

외부 링크를 추가하려면 일반적인 Markdown 구문을 사용하면 돼요.

For more information about KDoc syntax, see [KDoc](<example-URL>).

다음 단계

Kotlin의 문서 생성 도구를 사용하는 방법을 배워보세요: Dokka.