メインコンテンツまでスキップ

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 description.
@param[name] description.

@return​

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

@constructor​

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

@receiver​

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

@property name​

指定された名前を持つクラスのプロパティをドキュメント化します。このタグは、プロパティ定義の直前にドキュメントコメントを置くのが難しいプライマリコンストラクタで宣言されたプロパティをドキュメント化するために使用できます。

@throws class, @exception class​

メソッドによってスローされる可能性のある例外をドキュメント化します。Kotlinにはチェックされる例外がないため、可能なすべての例外をドキュメント化する必要はありませんが、クラスのユーザーに役立つ情報を提供する場合は、このタグを使用できます。

@sample identifier​

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

@see identifier​

ドキュメントの参考資料ブロックに、指定されたクラスまたはメソッドへのリンクを追加します。

@author​

ドキュメント化されている要素の作成者を指定します。

@since​

ドキュメント化されている要素が導入されたソフトウェアのバージョンを指定します。

@suppress​

生成されたドキュメントから要素を除外します。モジュールの公式APIの一部ではないが、外部から見える必要がある要素に使用できます。

注記

KDocは @deprecated タグをサポートしていません。代わりに、@Deprecated アノテーションを使用してください。

インラインマークアップ​

インラインマークアップの場合、KDocは通常のMarkdown構文を使用し、コード内の他の要素へのリンクをサポートするように拡張されています。

要素へのリンク​

別の要素（クラス、メソッド、プロパティ、またはパラメータ）にリンクするには、その名前を角括弧で囲むだけです。

この目的には、メソッド[foo]を使用してください。

リンクにカスタムラベルを指定する場合は、要素リンクの前にもう1セットの角括弧で囲んで追加します。

この目的には[このメソッド][foo]を使用してください。

要素リンクでは、完全修飾名も使用できます。Javadocとは異なり、完全修飾名は常にドット文字を使用してコンポーネントを区切ることに注意してください。これはメソッド名の前でも同様です。

クラスのプロパティを列挙するには、[kotlin.reflect.KClass.properties]を使用してください。

要素リンクの名前は、ドキュメント化されている要素内で名前が使用された場合と同じルールを使用して解決されます。特に、これは、名前を現在のファイルにインポートした場合、KDocコメントで使用するときに完全に修飾する必要がないことを意味します。

KDocには、リンク内のオーバーロードされたメンバーを解決するための構文がないことに注意してください。Kotlinのドキュメント生成ツールは、関数のすべてのオーバーロードのドキュメントを同じページに配置するため、リンクが機能するために特定のオーバーロードされた関数を識別する必要はありません。

外部リンク​

外部リンクを追加するには、一般的なMarkdown構文を使用します。

KDocの構文の詳細については、[KDoc](<example-URL>)を参照してください。

次のステップ​

Kotlinのドキュメント生成ツールであるDokkaの使用方法を学びましょう。