Kotlin 1.4的Dokaa Alpha版

我们已经在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中常见情况：

有关文档生成所需所有信息(包括源集的信息)，将自动与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中轻易地应用如下配置：

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

我们希望这种合并源集的支持能简化你的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体验最好的文档工具！