類似于Java中的JavaDoc工具，Kotlin的官方也發(fā)布了一款生成Kotlin文檔工具捉蚤。dokka
不過它確實(shí)不是很好用化借。
1.引入依賴
buildscript {
repositories {
jcenter()
}
dependencies {
classpath "org.jetbrains.dokka:dokka-gradle-plugin:0.9.17"
}
}
repositories {
jcenter() // or maven { url 'https://dl.bintray.com/kotlin/dokka' }
}
坑1：截止在我寫這邊文檔時(shí)候周偎，該工具的最新版本為0.10.0。在這個(gè)版本中嗽测，作者將兩個(gè)插件進(jìn)行了合并（一個(gè)適用于Android項(xiàng)目的插件绪励，一個(gè)則用于通用Kotlin項(xiàng)目插件）。導(dǎo)致了出現(xiàn)了一個(gè)大坑唠粥。詳情請見這里 [https://github.com/Kotlin/dokka/issues/213(https://github.com/Kotlin/dokka/issues/213)疏魏。
經(jīng)過一早上的踩坑折騰，發(fā)現(xiàn)在回退到上一個(gè)版本晤愧，0.9.17版本沒出現(xiàn)類似問題大莫。
2. 配置使用
apply plugin: 'kotlin-android-extensions'
apply plugin: 'kotlin-kapt'
// 添加插件
apply plugin: 'org.jetbrains.dokka-android'
...
android {
...
// 聲明dokka配置DSL
dokka {
// 輸出格式，目前支持五種官份，html, javadoc,html-as-java, markdown,kotlin-website*
outputFormat = 'html'
// 文檔輸出目錄
outputDirectory = "$buildDir/javadoc"
}
}
然后同步項(xiàng)目之后只厘，該插件會(huì)為項(xiàng)目添加一個(gè)dokka的task。
坑2：點(diǎn)擊執(zhí)行此任務(wù)之后舅巷。首先插件會(huì)構(gòu)建你項(xiàng)目中的所有的構(gòu)建變體（flavor）羔味。沒錯(cuò)，如果你的項(xiàng)目中有dev钠右，release變體赋元，那么這兩個(gè)變體都會(huì)構(gòu)建一遍，出現(xiàn)任何構(gòu)建不通過都會(huì)導(dǎo)致生成文檔失敗飒房。比如說搁凸。在某些構(gòu)建變體中沒有配置BuildConfig屬性，ManifestPalceHolder還未來得及配置狠毯，都會(huì)導(dǎo)致構(gòu)建不通過坪仇。
WTF，你就不能像JavaDoc那樣安安靜靜像生成個(gè)文檔垃你。。
坑3：GC overhead limit exceeded。解決了上一個(gè)問題惜颇，又出現(xiàn)了一個(gè)oom的問題皆刺。這個(gè)問題也算是常見，不過我這個(gè)總共不超過十個(gè)class文件凌摄，居然翻車了羡蛾。。好吧锨亏，果斷在根目錄下gradle.properties文件中配置擴(kuò)大一下堆棧大小
org.gradle.jvmargs=-Xmx4096m -XX:MaxPermSize=4096m -XX:+HeapDumpOnOutOfMemoryError
在成功構(gòu)建完所有的構(gòu)建變體任務(wù)后痴怨，終于看到了在輸出目錄outputDirectory中的出現(xiàn)了javadoc文件夾。
打開index頁面器予，你就可以看到dokka為項(xiàng)目生成的文檔了浪藻。
坑4：可以看到，dakko確實(shí)幫我們生成了類文檔乾翔，但是居然androidx開頭的是什么鬼爱葵？？打開一開里面全都是一些R文件的聲明反浓。
很明顯萌丈，dokka有點(diǎn)水土不服，因?yàn)樵赼ndroid構(gòu)建過程中確實(shí)會(huì)生成很多R文件雷则。
那我只想生成項(xiàng)目src目錄下的代碼文檔辆雾，其他的我統(tǒng)統(tǒng)不想要。怎么辦月劈？
翻遍了dakko文檔度迂，解決方案不是沒有，只是在我看來不是很完美艺栈。在dakko中是通過
packageOptions 這個(gè)DSL配置來聲明相關(guān)配置的英岭。比如：
dokka {
outputFormat = 'html'
outputDirectory = "$buildDir/javadoc"
packageOptions {
// 所操作的包的前綴，包括androidx一下所有的子包湿右。通配符無效
prefix = "androidx"
// 該包全部不生成文檔
suppress = true
}
}
在以上聲明中诅妹，dokka就不會(huì)為androidx作為包名前綴的類生成文檔。問題似乎得到了解決毅人。但是這是一種舍近求遠(yuǎn)的方法吭狡。就好比你去一家店想買一杯奶茶，老板居然問你不想喝什么口味的丈莺。划煮。因?yàn)樵诤罄m(xù)的開發(fā)中你可能還會(huì)引入新的包，dokka可能會(huì)為其他R文件生成以其他報(bào)名開頭的文檔缔俄。那么此時(shí)你必須繼續(xù)添加packageOptions配置弛秋。器躏。
