Kotlin: KDoc の書き方

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

Dokka

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

KDoc の構文

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

/**
* これはOK
*/
/**
コメントにはなるけどこれは KDoc ではない
*/

/**

* これはOK

/**

コメントにはなるけどこれは 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 { ... }
}

/**

* 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 { ... }

}

ブロックタグ

@param

構文

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

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

例

@param title タイトル
@param [description] 説明

1 2	@param title タイトル @param [description] 説明

@return

構文

@return 説明

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

例

@return 新しいインスタンス

1	@return 新しいインスタンス

@constructor

構文

@constructor 説明

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

例

@constructor 与えられた引数からプロパティを計算して代入します。

1	@constructor 与えられた引数からプロパティを計算して代入します。

@receiver

構文

@reveiver 説明

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

@property

構文

@property 名前説明

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

例

@property name 名前

1	@property name 名前

@throws, @exception

構文

@throws 例外クラス名説明
@exception 例外クラス名説明

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

例

@throws StandardException たまに発生する標準的なエラー
@exception StandardException たまに発生する標準的なエラー

1 2	@throws StandardException たまに発生する標準的なエラー @exception StandardException たまに発生する標準的なエラー

@sample

構文

@sample 関数名

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

例

@sample function1
@sample function2

1 2	@sample function1 @sample function2

@see

構文

@see クラス名・関数名

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

例

@see function1
@see AnotherClass

1 2	@see function1 @see AnotherClass

@author

構文

@author 書いた人

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

例

@author 変更 仕田人

1	@author 変更仕田人

@since

構文

@since 説

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

例

@since 1.0.0

1	@since 1.0.0

@suppress

構文

@supress

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

@Deprecated

構文

@Deprecated

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

インラインマークアップ

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

基本のマークダウン

em

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

*text* => <em>text</em>

1	text => <em>text</em>

strong

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

*text* => <em>text</em>**text** => <strong>text</strong>

1	text => <em>text</em>text => <strong>text</strong>

code

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

`text` => <code>text</code>
``text`text`` => <code>text`text</code>

1 2	`text` => <code>text</code> ``text`text`` => <code>text`text</code>

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

a

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

[an example](http://example.com/ "Title") =>
<a href=”http://example.com” title=”Title”>an example</a>
[an example](http://example.com) =>
<a href=”http://example.com”>an example</a>

[an example](http://example.com/ "Title") =>

<a href=”http://example.com” title=”Title”>an example</a>

[an example](http://example.com) =>

<a href=”http://example.com”>an example</a>

要素へのリンク

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

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

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

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

dokka {
// モジュール・パッケージのドキュメント(Markdown)リスト
includes = ['packages.md', 'extra.md']
}

dokka {

// モジュール・パッケージのドキュメント(Markdown)リスト

includes = ['packages.md', 'extra.md']

}

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

例

# Module モジュール1
モジュール1の説明
# Package パッケージ1
パッケージ1の説明
## Level 2 heading
パッケージ1のドキュメントとして扱われます。
# Package パッケージ2
パッケージ2の説明

# Module モジュール1

モジュール1の説明

# Package パッケージ1

パッケージ1の説明

## Level 2 heading

パッケージ1のドキュメントとして扱われます。

# Package パッケージ2

パッケージ2の説明

The Life