我们已经在Kotlin 1.4上发布了Dokka(Alpha)! 该发行版保证Dokka的版本与Kotlin编译器的最新稳定版本一致。 它着重于减少Dokka在最普遍场景下(包括Kotlin多平台项目)的配置项,能花费更少时间编写Dokka配置,意味着能有更多的时间来编写Kotlin文档!

我们在Kotlin 1.4.0-RC上发布了Dokka,而其中我们重新设计了文档引擎的大部分,并引入了许多新特性和改进,例如新的HTML格式,多模块项目和扩展性。
自那时起,我们从社区中收到了很多宝贵的反馈意见——从bug修复到多平台项目中更优的源集分组——我们合并到该版中。 下面来看看!
简化的Gradle插件
Dokka的这个版本,我们在保证支持高级配置情况下,尽力让Gradle插件更易于使用。实际上从现在开始,大多数项目通过Dokka生成文档都不需要任何手动配置!只需添加Dokka Gradle插件便足以涵盖build.gradle.kts
中常见情况:
1 2 3 |
plugins { id("org.jetbrains.dokka") version “1.4.0” } |
有关文档生成所需所有信息(包括源集的信息),将自动与Kotlin Gradle插件保持同步。 已注册或Kotlin监视的每个源集也将自动应用Dokka中的深度配置。
剩下要做的就是执行Dokka任务 例如dokkaHtml
或dokkaJavadoc
)以生成项目的文档。当然,你仍可以通过进一步的配置让Dokka满足特定的要求,或者使用高级功能。
我们希望消除大量需要手动的配置,完善”自动配置”机制并使其更加直观,我们可以让用户更轻松地开始使用Dokka生成文档。
多平台
上一节介绍的默认配置也适用于多平台项目。只需应用Dokka Gradle插件,所有平台特定的源集将自动与Kotlin模组同步。对于大多数项目,不再需要在Dokka中注册其他源集,这意味着可以从配置文件中删除冗余信息。 为了简单地控制不同平台的处理方式,我们还引入了一种直接的方法来合并多个源集。
合并源集
默认情况下,Dokka会在项目中为每个源集显示一个“气泡”(平台标记),这是一个将文档过滤为指定目标API的快捷方法。但如果在一个有大量源集的项目中,例如面向多个native目标的Kotlin多平台项目,那么该预览会很快变得混乱。例如这个kotlinx-coroutines的示例:

之前,需要复杂的配置才能将这些相关源集组合到单个“气泡”中,但反过来看又在项目构建文件中引入了不必要的复杂性。
因为我们看到社区及Kotlin官方的项目都对这种分组功能的强烈需求,所以我们引入了一种更新更为简化的机制来解决源集的合并。表示相同平台(通用,JVM,JS或Native)且具有相同displayName
的所有源集都将合并到相同的“气泡”中。
例如,要将所有Native源集归到“Native气泡”下,你可以在build.gradle.kts
中轻易地应用如下配置:
1 2 3 4 5 6 7 8 9 |
tasks.withType<DokkaTask>().configureEach { dokkaSourceSets { configureEach { if (platform.get() == native) { displayName.set("native") } } } } |
重新生成文档后,你将看到更加简洁的源集“气泡”列表:

我们希望这种合并源集的支持能简化你的Dokka配置,并替代此前的其他方案。
兼容性和稳定性说明
请注意,Dokka for Kotlin 1.4.0是[Alpha]((https://kotlinlang.org/docs/reference/evolution/components-stability.html#stability-levels-explained)版本。 Gradle插件的API可能会在将来的Dokka版本中变动。
Dokka for Kotlin 1.4.0与Kotlin Gradle插件更加紧密地集成在一起,并保证同步相关的配置信息。为了推进这些新的集成机制,我们将Gradle切换到新的Provider和Property API,这破坏了当前的配置API。导致现在通过.set()
而非=
来为属性赋值,例如:
1 |
jdkVersion.set(8) |
有关DSL配置变动及改进的详细描述,包括期待已久的基于java.io.File
的API替换基于字符串的API,请查看我们的迁移指南。
如何尝试
要在项目中使用最新版本的Dokka,请将相应的配置项添加到build.gradle(.kts)
文件顶部:
1 2 3 4 |
plugins { // ... id("org.jetbrains.dokka") version "1.4.0" } |
我们希望该版本Dokka引入的特性,能让你为项目中创建优雅且易于阅读的文档更加轻松和高效。
继续帮助我们改进Dokka
我们依赖你的反馈来持续完善Dokka。如果遇到任何问题,请在Dokka的GitHub问题跟踪器中报告。你也可以加入官方Kotlin Slack的#dokka
频道参与讨论。
在这里,我们要特别感谢所有反馈并报告问题的人。我们谨记你的关心与建议,我们正在努力让Dokka成为Kotlin体验最好的文档工具!