Kotlin: KDoc の書き方


Kotlin のコードのドキュメンテーションに使われるのが KDoc です。 Java でいう JavaDoc に相当します。 KDoc は JavaDoc の構文をサポートし、インラインマークアップも使えるようになっています。 Javadoc は KDoc をサポートしませんので、 Kotlin と Java が混在する環境でのドキュメント作成には向いていません。

Dokka

Kotlin のドキュメント作成のツールは Dokka です。 Dokka には Gradle, Maven, Ant それぞれのプラグインがありますので、ビルドプロセスの中に容易に組み込むことができます。

KDoc の構文

JavaDoc と同じように、 KDoc は /** で始まり */ で終わります。 全てのコメントはアスタリスクの右側に書きます。

KDoc では一般的に、最初の段落を各項目の要約にして、 続く文章で詳細を説明します。 後に説明するブロックタグは @ から始まります。

ドキュメント例

ブロックタグ

@param

構文

  1. @param [name] 説明
  2. @param name 説明

関数のパラメータ、クラスやプロパティ、関数の型パラメータを記述するのに使われます。 上の構文1ではパラメータとその説明を明確に区別するために、パラメータ名を [ ] で囲んでいます。 構文1, 2 は同等のものとして扱われます。

@return

構文

@return 説明

関数の返り値について記述します。

@constructor

構文

@constructor 説明

クラスのプライマリコンストラクタについての説明を記述します。

@receiver

構文

@reveiver 説明

拡張関数のレシーバについての説明を記述します。

@property

構文

@property 名前 説明

クラスのプロパティについて記述します。 このタグではプライマリコンストラクタで宣言されたプロパティについて記述できます。 プロパティの定義の直前ではなく、クラスのドキュメントの中に記述するのがよいとされています。

@throws, @exception

構文

  1. @throws 例外クラス名 説明
  2. @exception 例外クラス名 説明

関数の中で発生しうる例外クラスを記述します。 Kotlin には検査例外がありませんし、このブロックタグも強制ではありません。 しかし、ユーザに情報として提供できる場合はこのブロックタグを使います。 複数ある場合は複数回記述します。 @throw, @exception のいずれを使っても出力は同じになります。

@sample

構文

@sample 関数名

要素が使われている関数を記述します。 このようにすると、ドキュメントの中に指定された関数の実装が表示されますので、この関数がどのように使われるかの例を示すことができます。 複数ある場合は複数回 @sample を記述します。 コード内の関数をサンプルとして示すこともできますし、サンプル用の Kotlin のコードを作成して、そこにある関数をサンプルとして指定することもできます。

@see

構文

@see クラス名・関数名

関連するクラス、関数があれば記述します。 複数ある場合は @see を複数回使います。

@author

構文

@author 書いた人

作者を明らかにするために記述します。

@since

構文

@since 説

指定されたドキュメントがどのバージョンから導入されたかを記述します。

@suppress

構文

@supress

指定した要素を作成されるドキュメントから除外します。 例えば公式の API ではないが外部から利用可能になっているべき要素に使用します。

@Deprecated

構文

@Deprecated

非推奨の要素に記述します。 @deprecated タグ は KDoc で利用できませんので、 この @Deprecated タグ を使用します。

インラインマークアップ

KDoc では標準的なマークダウン構文が使えます。 それに加えて、コード内の他の要素にリンクするための簡潔な構文をサポートしています。

基本のマークダウン

em

* でテキストを囲むと、 強調を表す em タグ になります。

strong

** でテキストを囲むと、 重要性を表す strong タグ になります。

code

でテキストを囲むと code タグ になります。 コードの中に 文字としての がある場合は でテキストを囲みます。

ひとまとまりのコードを出力したい場合には、 ` または インデント が使えます。 <pre><code>, </code></pre> でコードを囲んで出力します。

a

[ ]( )a タグ を作ることができます。 [ ] 内に表示したい文字列、 ( ) 内にリンクしたい URL と タイトル属性を記述します。 タイトル属性は省略することができます。

要素へのリンク

クラス、メソッド、プロパティ、パラメータといった他の要素にリンクするには、コメント内の要素名を [ ] で囲みます。

モジュール・パッケージのドキュメンテーション

モジュール・パッケージのドキュメンテーションは、Kotlinのファイルとは別にマークアップファイルを作って記述します。

ビルドの際に、 -incldude を使ってパラメータで指定するか、 build.gradle の中に次のように記述する必要があります。

モジュールおよびパッケージのドキュメントは、レベル1のヘッダから始める必要があり、 モジュールの場合は # Module モジュール名 、 パッケージの場合は # Package パッケージ名 というように記述する必要があります