基于Kotlin 1.4.0-RC的Dokka预览

这篇博客由*PawełMarks *和* KamilDoległo*撰写。

每一个编程语言的生态都需要文档支撑才能蓬勃发展。 Kotlin起源于JVM生态，在Java生态中Javadoc是一个标准且被普遍接受的文档引擎。Kotlin自然会被期待类似无缝衔接的工具。那是Dokka的诞生初衷–提供可靠且简单的文档引擎。但是随着Kotlin的特性不断增加，多平台项目，支持Native等，Dokka也变得更为复杂。

Kotlin 1.4持续以来的开发给了我们一个重新思考，重新设计和重新实现Dokka(其版本号现在与Kotlin嵌入式编译器一致)的机会。在这篇博客中，我们为你概述Dokka的新特性，并公布其预览版本。如果你能尝试并分享反馈，我们将不胜感激。

如何尝试

Dokka以两个最流行的Kotlin构建工具(Maven和Gradle)的插件进行分发。对于高级用例，Dokka可用作独立的命令行应用程序。对于基于Gradle的项目，只需将以下内容添加到项目的build.gradle或build.gradle.kts文件中：

运行./gradlew dokkaHtml之后，你应该能在项目构建目录内的dokka目录中看到生成的文档。

新的HTML格式

我们的主要目标之一是无需用户进行任何调整和配置便可生成美观，现代的文档。这就是为什么Dokka的默认呈现不再是简单静态网页的原因。让我们快速浏览一下新HTML格式最重要的特性。请注意，我们已经使用了协程文档来演示新的Dokka格式，但是该文档不久之后才会采用。

导航树

在屏幕的左侧，你可以在分层菜单中看到已被组织好的所有项目模块，程序包及类型。这使你不仅可以一目了然地查看项目结构，还可以在代码库的不同部分之间快速导航。

搜索栏

如果你的项目特别复杂，或者你不知道其代码库结构，但需要查找某种类型或功能，则可以使用内置的搜索栏。它知道项目中的所有符号，因此可以为搜索查询提供类似IDE的自动补全功能。

源码链接

如果你的项目代码已被在线托管，则Dokka可以从代码中的任何符号链接到其定义位置。只需将sourceLink选项作为生成参数来配置repo URL，所有的函数和类型会链接到定义它们的准确代码行。

平台相关信息

Kotlin是一个跨平台语言，其文档引擎需要顾及所有对终端用户也许会很重要的平台信息。在多平台项目的文档中，你会注意到，每个符号都被标记其适用于哪个平台。此外，如果同一符号其不同平台的文档或签名存在差异，则可以通过选项卡进行切换。

在每个页面你可以显示或隐藏指定平台中定义的符号。

可执行示例

Kotlin有一个很棒的工具，叫Kotlin Playground，让你能从浏览器中运行简单的代码片段。该工具已和和Dokka集成。你可以指定示例的来源，它们将包含到文档中，让用户能了解如何使用你的库。你只需要创建普通的Kotlin文件编写代码，并通过 samples = listOf(<paths to the files>) 及 @sample <fully qualified name of your method> 链接到需要的方法，Dokka将自动复制源代码来创建可执行的代码块。

其余格式化

Markdown

Dokka支持将文档托管在GitHub页面或其他支持markdown格式的网站上。无需任何配置即可使用，支持Markdown的两种不同样式– Jekyll和GFM(GitHub Flavored Markdown)。只需要执行dokkaJekyll或dokkaGfm任务便可使用它们。

Kotlin-as-java and javadoc

Kotlin支持与Java互操作，这意味着Java项目可使用面向JVM的Kotlin库。 Dokka也能为它们生成文档。你只需要将HTML格式添加到dokkaHtmlPlugin("org.jetbrains.dokka：kotlin-as-java-plugin：1.4.0-rc")或为GFM和Jekyll添加dokkaGfmPlugin(...)或dokkaJekyllPlugin(...)格式。类和函数将以类似Java的格式呈现，例如，类的属性将变更为适当的get和set方法。多得益于我们的新架构，Kotlin-as-java插件可与HTML，GFM和Jekyll Markdown以及用户自定义的格式一起使用。

举一反三，不仅可将属性脱糖到getter和setter上，还可以像Javadoc一样生成文档。只需要执行dokkaJavadoc任务。新的Javadoc完全独立于JDK工件，因此能保证和JDK(8及更高版本)一起使用。

多模块项目

默认情况下，Dokka会为每个Kotlin模块生成一份文档。

• 执行dokkaHtmlCollector任务来汇总全部模块的所有定义，并将它们定义为单个模块。通过这种方式，可以在只有一份文档情况下，将代码划分为小模块。
• 执行dokkaHtmlMultimodule任务在单独的目录中为每个模块生成文档，然后创建带有索引的公共页面，索引链接到所有模块的文档简介。可以在Markdown文件中提供模板来自定义该页面。

其他特性

尽管Dokka 1.4已完全重写，我们也希望保留以前发行版中的所有有用功能和配置项。仍然可以：

• 生成Java和Kotlin混合源的文档。
• 含项目，模块和包页面的Markdown文档。
• 生成非公共符号的文档。
• 文档生成后，输出有关每个未记录符号的报告。
• 指定单个软件包的所有生成配置项。

扩展性

新的Dokka具有灵活而强大的插件系统。 Jekyll，GFM，kotlin-as-java和Javadoc只是新Dokka插件的一些示例。现在，所有人都可以提供自定义格式或任何充满想象的方式转换文档。得益于强大的框架，其直观易用，且对项目毫无破坏性。如果你对插件开发感兴趣，请查看开发人员指南。