KDocのドキュメント記述例を紹介します。
KDocを使えばKotlinのソースコードに書いたコメントからドキュメントを作成することが出来ます。後々、クラスの再利用を考えているなら、ドキュメントを残して再利用性を高めておきましょう！
KDocとは
KDocとはソースコード埋め込み型のドキュメント生成言語です。機能面で比較すればJavadocのKotlin版に相当するのがKDocです。
ソースコードのコメントにKDocがサポートするタグ（Javadocと同じタグが使える）を埋め込んでおくと、ドキュメント生成エンジンのDokkaがタグの指示に従ってドキュメントを作成してくれます。タグに加えてMarkdownも組み合わせることが出来て、ドキュメントの装飾がしやすくなっています。
KDocのさらなる情報はここを参照してください。
Dokkaのさらなる情報はここを参照してください。
Marddownのさらなる情報はここを参照してください。
環境設定
KDocを使うためにbuild.gradleへプラグインの組み込みを宣言します。
buildscript {
ext.kotlin_version = '1.3.72'
ext.dokka_version = '0.10.1'
repositories {
google()
jcenter()
}
dependencies {
classpath 'com.android.tools.build:gradle:3.6.3'
classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
classpath "org.jetbrains.dokka:dokka-gradle-plugin:$dokka_version"
// NOTE: Do not place your application dependencies here; they belong
// in the individual module build.gradle files
}
}
...
apply plugin: 'com.android.application'
apply plugin: 'kotlin-android'
apply plugin: 'kotlin-android-extensions'
apply plugin: 'org.jetbrains.dokka'
android {
...
dokka {
outputFormat = 'html'
outputDirectory = "$buildDir/MyAppDoc"
configuration {
androidVariants = ["debug", "release"]
}
}
}
...
ドキュメント記述例
「/**～*/」の範囲に記述されたコメントがドキュメント生成の対象になります。
タグはJavadocと同じもの使えます。さらに、KDocで追加されたものがあります。
Markdownは一部の構文をサポートしています。記述例に記述したものは使用できました。
package com.example.android.app.myapp
/**
* トップレベル変数(regE)の説明.
*
* 変数(regE)の詳細な説明を記入する部分です.
* ほげほげ、しかじか、るんるん.
*/
val regE: String = "EEE"
/**
* トップレベル変数(regF)の説明.
*
* 変数(regF)の詳細な説明を記入する部分です.
* ほげほげ、しかじか、るんるん.
*/
var regF: Int = 333
/**
* トップレベル関数(procZ)の説明.
*
* 関数(procZ)の詳細な説明を記入する部分です.
* ほげほげ、しかじか、るんるん.
*
* @param msg 変数(msg)の説明.
* @param num 変数(mun)の説明.
* @return 戻り値の説明.
*/
fun procZ(msg: String, num: Int): String {
return "msg_${num}"
}
/**
* クラス(Sample)の説明.
*
* Document(KDoc)をテストするためのサンプルです.ここはクラスの詳細な説明を
* 記入する部分です.
*
* -------- ここから Markdownの記述 --------
*
* # 見出し1：Markdownも使えます
* すべての構文は使えないようだ。
* Line,Table,引用,HTMLのタグは使えない。ここで記述したものは使用できた。
*
* 段落の開始は空行が必要！上のように空行を入れれば、文章が行頭から開始されます。
*
* ## 見出し2：リスト
* 今日は**今日**の風が吹いている。
* - リスト
* - リスト
* 1. リスト
* 1. リスト
*
* ## 見出し2：コードブロック
* 明日は**明日**の風が吹くだろう。
* ```
* fun procY(msg: String, num: Int): String {
* return "msg_${num}"
* }
* ```
*
* ## 見出し2：リンク
* 昨日は**昨日**の風が吹いた。
*
* リンクも「[ブログのホームへ移動](https://android.suzu-sd.com/)」貼れます。
*
* リンクも「[procZ]」貼れます。
*
* リンクも「[procZ関数へ飛ぶ][procZ]」貼れます。
*
* -------- ここまで Markdownの記述 --------
*
* @constructor コンストラクタの説明.
*
* コンストラクタの詳細な説明を記入する部分です.
* ほげほげ、しかじか、るんるん.
*
* @property arg1 プロパティ(arg1)の説明.
*
* プロパティ(arg1)の詳細な説明を記入する部分です.
* ほげほげ、しかじか、るんるん.
*
* @property arg2 プロパティ(arg2)の説明.
*
* プロパティ(arg2)の詳細な説明を記入する部分です.
* ほげほげ、しかじか、るんるん.
*/
class Sample(val arg1: String, var arg2: Int) { // <-constructorキーワードは省略
/**
* セカンダリコンストラクタの説明.
*
* セカンダリコンストラクタの詳細な説明を記入する部分です.
* ほげほげ、しかじか、るんるん.
*/
constructor(arg1: String) :this(arg1, 12) {}
/**
* プロパティ(regC)の説明.
*
* プロパティ(regC)の詳細な説明を記入する部分です.
* ほげほげ、しかじか、るんるん.
*/
val regC: String = "CCC"
/**
* プロパティ(regD)の説明.
*
* プロパティ(regD)の詳細な説明を記入する部分です.
* ほげほげ、しかじか、るんるん.
*/
var regD: Int = 222
/**
* 関数(procY)の説明.
*
* 関数(procY)の詳細な説明を記入する部分です.
* ほげほげ、しかじか、るんるん.
*
* @param msg 変数(msg)の説明.
* @param num 変数(mun)の説明.
* @return 戻り値の説明.
*/
fun procY(msg: String, num: Int): String {
return "msg_${num}"
}
// ------------------------------------------------------------------------
/**
* コンパニオンブロックの説明. <--【ここは掲載されない】
*
* Document(KDoc)をテストするためのサンプルです.ここはコンパニオンの
* 詳細な説明を記入する部分です. <--【ここは掲載されない】
*/
companion object {
/**
* コンパニオンプロパティ(regA)の説明.
*
* プロパティ(regA)の詳細な説明を記入する部分です.
* ほげほげ、しかじか、るんるん.
*/
val regA: String = "AAA"
/**
* コンパニオンプロパティ(regB)の説明.
*
* プロパティ(regB)の詳細な説明を記入する部分です.
* ほげほげ、しかじか、るんるん.
*/
var regB: Int = 111
/**
* コンパニオン関数(procX)の説明.
*
* 関数(procX)の詳細な説明を記入する部分です.
* ほげほげ、しかじか、るんるん.
*
* @param msg 変数(msg)の説明.
* @param num 変数(mun)の説明.
* @return 戻り値の説明.
*/
fun procX(msg: String, num: Int): String {
return "msg_${num}"
}
}
}
ドキュメントの生成
プラグインが組み込まれていれば、Gradleからタスクdokkaが実行できます。
タスクを実行するとoutputDirectory で指定したフォルダにhtmlファイルが作成されます。
KDocフォーマット
「outputFormat = ‘html’」はKDocフォーマットのhtmlファイルを出力します。
KDocフォーマットの出力結果を参照してください（記述例をドキュメント化したものです）。
Javadocフォーマット
「outputFormat = ‘javadoc’」はJavadocフォーマットのhtmlファイルを出力します。
Javadocフォーマットの出力結果を参照してください（記述例をドキュメント化したものです）。