这篇博客由*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文件中:
1 2 3 4 5 6 |
plugins { id("org.jetbrains.dokka") version "1.4.0-rc" } repositories { jcenter() } |
运行./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插件的一些示例。现在,所有人都可以提供自定义格式或任何充满想象的方式转换文档。得益于强大的框架,其直观易用,且对项目毫无破坏性。如果你对插件开发感兴趣,请查看开发人员指南。
Pingback引用通告: Kotlin 1.4的Dokaa Alpha版 - KotlinCn