Kotlin 1.4的Dokaa Alpha版

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

img

我们在Kotlin 1.4.0-RC上发布了Dokka,而其中我们重新设计了文档引擎的大部分,并引入了许多新特性和改进,例如新的HTML格式多模块项目扩展性

自那时起,我们从社区中收到了很多宝贵的反馈意见——从bug修复到多平台项目中更优的源集分组——我们合并到该版中。 下面来看看!

简化的Gradle插件

Dokka的这个版本,我们在保证支持高级配置情况下,尽力让Gradle插件更易于使用。实际上从现在开始,大多数项目通过Dokka生成文档都不需要任何手动配置!只需添加Dokka Gradle插件便足以涵盖build.gradle.kts中常见情况:

有关文档生成所需所有信息(包括源集的信息),将自动与Kotlin Gradle插件保持同步。 已注册或Kotlin监视的每个源集也将自动应用Dokka中的深度配置。

剩下要做的就是执行Dokka任务 例如dokkaHtmldokkaJavadoc)以生成项目的文档。当然,你仍可以通过进一步的配置让Dokka满足特定的要求,或者使用高级功能。

我们希望消除大量需要手动的配置,完善”自动配置”机制并使其更加直观,我们可以让用户更轻松地开始使用Dokka生成文档。

多平台

上一节介绍的默认配置也适用于多平台项目。只需应用Dokka Gradle插件,所有平台特定的源集将自动与Kotlin模组同步。对于大多数项目,不再需要在Dokka中注册其他源集,这意味着可以从配置文件中删除冗余信息。 为了简单地控制不同平台的处理方式,我们还引入了一种直接的方法来合并多个源集。

合并源集

默认情况下,Dokka会在项目中为每个源集显示一个“气泡”(平台标记),这是一个将文档过滤为指定目标API的快捷方法。但如果在一个有大量源集的项目中,例如面向多个native目标的Kotlin多平台项目,那么该预览会很快变得混乱。例如这个kotlinx-coroutines的示例:

img

之前,需要复杂的配置才能将这些相关源集组合到单个“气泡”中,但反过来看又在项目构建文件中引入了不必要的复杂性。

因为我们看到社区及Kotlin官方的项目都对这种分组功能的强烈需求,所以我们引入了一种更新更为简化的机制来解决源集的合并。表示相同平台(通用,JVM,JS或Native)且具有相同displayName的所有源集都将合并到相同的“气泡”中。

例如,要将所有Native源集归到“Native气泡”下,你可以在build.gradle.kts中轻易地应用如下配置:

重新生成文档后,你将看到更加简洁的源集“气泡”列表:

img

我们希望这种合并源集的支持能简化你的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()而非=来为属性赋值,例如:

有关DSL配置变动及改进的详细描述,包括期待已久的基于java.io.File的API替换基于字符串的API,请查看我们的迁移指南

如何尝试

要在项目中使用最新版本的Dokka,请将相应的配置项添加到build.gradle(.kts)文件顶部:

我们希望该版本Dokka引入的特性,能让你为项目中创建优雅且易于阅读的文档更加轻松和高效。

继续帮助我们改进Dokka

我们依赖你的反馈来持续完善Dokka。如果遇到任何问题,请在Dokka的GitHub问题跟踪器中报告。你也可以加入官方Kotlin Slack#dokka频道参与讨论。

在这里,我们要特别感谢所有反馈并报告问题的人。我们谨记你的关心与建议,我们正在努力让Dokka成为Kotlin体验最好的文档工具!

此条目发表在官方分类目录。将固定链接加入收藏夹。

发表评论

电子邮件地址不会被公开。 必填项已用*标注