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

関数の値パラメータ、またはクラス、プロパティ、関数の型パラメータをドキュメント化します。 パラメータ名と説明をより明確に分けるために、お好みでパラメータ名を括弧で囲むこともできます。したがって、以下の2つの構文は同等です。

@param name 説明。
@param[name] 説明。

@return

関数の戻り値をドキュメント化します。

@constructor

クラスのプライマリコンストラクタをドキュメント化します。

@receiver

拡張関数のレシーバーをドキュメント化します。

@property name

指定された名前を持つクラスのプロパティをドキュメント化します。このタグは、プライマリコンストラクタで宣言されたプロパティをドキュメント化する場合に使用できます。プロパティ定義の直前にドキュメントコメントを配置するのが不自然な場合に便利です。

@throws class, @exception class

メソッドによってスローされる可能性のある例外をドキュメント化します。Kotlinにはチェック例外（checked exceptions）がないため、考えられるすべての例外をドキュメント化することは期待されていませんが、クラスの利用者に有用な情報を提供する場合にこのタグを使用できます。

@sample identifier

指定された完全修飾名（qualified name）を持つ関数の本体を、現在の要素のドキュメントに埋め込み、その要素の使用例を表示します。

@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。