目次
Kotlin のコードのドキュメンテーションに使われるのが KDoc です。 Java でいう JavaDoc に相当します。 KDoc は JavaDoc の構文をサポートし、インラインマークアップも使えるようになっています。 Javadoc は KDoc をサポートしませんので、 Kotlin と Java が混在する環境でのドキュメント作成には向いていません。
Dokka
Kotlin のドキュメント作成のツールは Dokka です。 Dokka には Gradle, Maven, Ant それぞれのプラグインがありますので、ビルドプロセスの中に容易に組み込むことができます。
KDoc の構文
JavaDoc と同じように、 KDoc は /**
で始まり */
で終わります。 全てのコメントはアスタリスクの右側に書きます。
1 2 3 4 5 6 7 |
/** * これはOK */ /** コメントにはなるけどこれは KDoc ではない */ |
KDoc では一般的に、最初の段落を各項目の要約にして、 続く文章で詳細を説明します。 後に説明するブロックタグは @
から始まります。
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 |
/** * 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 は同等のものとして扱われます。
1 2 |
@param title タイトル @param [description] 説明 |
@return
構文
@return 説明
関数の返り値について記述します。
1 |
@return 新しいインスタンス |
@constructor
構文
@constructor 説明
クラスのプライマリコンストラクタについての説明を記述します。
1 |
@constructor 与えられた引数からプロパティを計算して代入します。 |
@receiver
構文
@reveiver 説明
拡張関数のレシーバについての説明を記述します。
@property
構文
@property 名前 説明
クラスのプロパティについて記述します。 このタグではプライマリコンストラクタで宣言されたプロパティについて記述できます。 プロパティの定義の直前ではなく、クラスのドキュメントの中に記述するのがよいとされています。
1 |
@property name 名前 |
@throws, @exception
構文
@throws 例外クラス名 説明
@exception 例外クラス名 説明
関数の中で発生しうる例外クラスを記述します。 Kotlin には検査例外がありませんし、このブロックタグも強制ではありません。 しかし、ユーザに情報として提供できる場合はこのブロックタグを使います。 複数ある場合は複数回記述します。 @throw
, @exception
のいずれを使っても出力は同じになります。
1 2 |
@throws StandardException たまに発生する標準的なエラー @exception StandardException たまに発生する標準的なエラー |
@sample
構文
@sample 関数名
要素が使われている関数を記述します。 このようにすると、ドキュメントの中に指定された関数の実装が表示されますので、この関数がどのように使われるかの例を示すことができます。 複数ある場合は複数回 @sample を記述します。 コード内の関数をサンプルとして示すこともできますし、サンプル用の Kotlin のコードを作成して、そこにある関数をサンプルとして指定することもできます。
1 2 |
@sample function1 @sample function2 |
@see
構文
@see クラス名・関数名
関連するクラス、関数があれば記述します。 複数ある場合は @see を複数回使います。
1 2 |
@see function1 @see AnotherClass |
@author
構文
@author 書いた人
作者を明らかにするために記述します。
1 |
@author 変更 仕田人 |
@since
構文
@since 説
指定されたドキュメントがどのバージョンから導入されたかを記述します。
1 |
@since 1.0.0 |
@suppress
構文
@supress
指定した要素を作成されるドキュメントから除外します。 例えば公式の API ではないが外部から利用可能になっているべき要素に使用します。
@Deprecated
構文
@Deprecated
非推奨の要素に記述します。 @deprecated
タグ は KDoc で利用できませんので、 この @Deprecated
タグ を使用します。
インラインマークアップ
KDoc では標準的なマークダウン構文が使えます。 それに加えて、コード内の他の要素にリンクするための簡潔な構文をサポートしています。
基本のマークダウン
em
*
でテキストを囲むと、 強調を表す em
タグ になります。
1 |
*text* => <em>text</em> |
strong
**
でテキストを囲むと、 重要性を表す strong
タグ になります。
1 |
*text* => <em>text</em>**text** => <strong>text</strong> |
code
がある場合は でテキストを囲むと
code
タグ になります。 コードの中に 文字としての でテキストを囲みます。
1 2 |
`text` => <code>text</code> ``text`text`` => <code>text`text</code> |
ひとまとまりのコードを出力したい場合には、
または インデント が使えます。 `
<pre><code>
, </code></pre>
でコードを囲んで出力します。
a
[ ]( )
で a
タグ を作ることができます。 [ ]
内に表示したい文字列、 ( )
内にリンクしたい URL と タイトル属性を記述します。 タイトル属性は省略することができます。
1 2 3 4 |
[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
の中に次のように記述する必要があります。
1 2 3 4 |
dokka { // モジュール・パッケージのドキュメント(Markdown)リスト includes = ['packages.md', 'extra.md'] } |
モジュールおよびパッケージのドキュメントは、レベル1のヘッダから始める必要があり、 モジュールの場合は # Module モジュール名
、 パッケージの場合は # Package パッケージ名
というように記述する必要があります
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
# Module モジュール1 モジュール1の説明 # Package パッケージ1 パッケージ1の説明 ## Level 2 heading パッケージ1のドキュメントとして扱われます。 # Package パッケージ2 パッケージ2の説明 |