Kotlin 코드 문서화: KDoc

Kotlin 코드 문서화에 사용되는 언어(Java의 Javadoc과 동일)를 KDoc이라고 합니다. KDoc은 기본적으로 블록 태그에 대한 Javadoc의 구문(Kotlin의 특정 구조를 지원하도록 확장됨)과 인라인 마크업에 대한 Markdown을 결합합니다.

노트

Kotlin의 문서 엔진인 Dokka는 KDoc을 이해하며 다양한 형식으로 문서를 생성하는 데 사용할 수 있습니다. 자세한 내용은 Dokka 문서를 참조하십시오.

KDoc 구문

Javadoc과 마찬가지로 KDoc 주석은 /**로 시작하여 */로 끝납니다. 주석의 각 줄은 별표로 시작할 수 있으며, 이는 주석 내용의 일부로 간주되지 않습니다.

일반적으로 문서 텍스트의 첫 번째 단락(첫 번째 빈 줄까지의 텍스트 블록)은 요소에 대한 요약 설명이고, 다음 텍스트는 자세한 설명입니다.

모든 블록 태그는 새 줄에서 시작하고 @ 문자로 시작합니다.

다음은 KDoc을 사용하여 문서화된 클래스의 예입니다.

/**
 * *멤버* 그룹입니다.
 *
 * 이 클래스에는 유용한 로직이 없습니다. 문서화 예제일 뿐입니다.
 *
 * @param T 이 그룹의 멤버 유형입니다.
 * @property name 이 그룹의 이름입니다.
 * @constructor 빈 그룹을 만듭니다.
 */
class Group<T>(val name: String) {
    /**
     * 이 그룹에 [member]를 추가합니다.
     * @return 그룹의 새 크기입니다.
     */
    fun add(member: T): Int { ... }
}

블록 태그

KDoc은 현재 다음 블록 태그를 지원합니다.

@param name

함수의 값 파라미터 또는 클래스, 속성 또는 함수의 타입 파라미터를 문서화합니다. 파라미터 이름과 설명을 더 잘 구분하기 위해 파라미터 이름을 괄호로 묶을 수 있습니다. 따라서 다음 두 구문은 동일합니다.

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

@return

함수의 반환 값을 문서화합니다.

@constructor

클래스의 기본 생성자를 문서화합니다.

@receiver

확장 함수의 수신자를 문서화합니다.

@property name

지정된 이름을 가진 클래스의 속성을 문서화합니다. 이 태그는 속성 정의 바로 앞에 문서 주석을 넣는 것이 어색한 기본 생성자에서 선언된 속성을 문서화하는 데 사용할 수 있습니다.

@throws class, @exception class

메서드에서 throw될 수 있는 예외를 문서화합니다. Kotlin에는 checked exception이 없으므로 가능한 모든 예외를 문서화해야 하는 것은 아니지만 클래스 사용자에게 유용한 정보를 제공하는 경우 이 태그를 사용할 수 있습니다.

@sample identifier

지정된 정규화된 이름을 가진 함수의 본문을 현재 요소에 대한 문서에 포함하여 요소 사용 방법에 대한 예제를 보여줍니다.

@see identifier

문서의 See also 블록에 지정된 클래스 또는 메서드에 대한 링크를 추가합니다.

@author

문서화되는 요소의 작성자를 지정합니다.

@since

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

@suppress

생성된 문서에서 요소를 제외합니다. 모듈의 공식 API의 일부가 아니지만 외부적으로 표시되어야 하는 요소에 사용할 수 있습니다.

노트

KDoc은 @deprecated 태그를 지원하지 않습니다. 대신 @Deprecated 어노테이션을 사용하십시오.

인라인 마크업

인라인 마크업의 경우 KDoc은 일반적인 Markdown 구문을 사용하며 코드의 다른 요소에 연결하기 위한 약식 구문을 지원하도록 확장되었습니다.

요소 링크

다른 요소(클래스, 메서드, 속성 또는 파라미터)에 연결하려면 해당 이름을 대괄호 안에 넣으십시오.

이 목적을 위해 [foo] 메서드를 사용하십시오.

링크에 대한 사용자 정의 레이블을 지정하려면 요소 링크 앞에 다른 대괄호 세트에 추가하십시오.

이 목적을 위해 [이 메서드][foo]를 사용하십시오.

요소 링크에서 정규화된 이름을 사용할 수도 있습니다. Javadoc과 달리 정규화된 이름은 메서드 이름 앞에서도 항상 점 문자를 사용하여 구성 요소를 구분합니다.

[kotlin.reflect.KClass.properties]를 사용하여 클래스의 속성을 열거하십시오.

요소 링크의 이름은 문서화되는 요소 내부에서 이름을 사용하는 것과 동일한 규칙을 사용하여 확인됩니다. 특히, 이는 현재 파일로 이름을 가져온 경우 KDoc 주석에서 이름을 사용할 때 완전히 정규화할 필요가 없음을 의미합니다.

KDoc에는 링크에서 오버로드된 멤버를 확인하기 위한 구문이 없습니다. Kotlin의 문서 생성 도구는 함수의 모든 오버로드에 대한 문서를 동일한 페이지에 배치하므로 링크가 작동하려면 특정 오버로드된 함수를 식별할 필요가 없습니다.

외부 링크

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

KDoc 구문에 대한 자세한 내용은 [KDoc](<example-URL>)을 참조하십시오.

다음 단계

Kotlin의 문서 생성 도구인 Dokka 사용법을 알아보십시오.