基于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的新特性,并公布其预览版本。如果你能尝试并分享反馈,我们将不胜感激。

file

如何尝试

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

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

新的HTML格式

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

导航树

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

搜索栏

img

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

源码链接

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

平台相关信息

img

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

img

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

可执行示例

img

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)。只需要执行dokkaJekylldokkaGfm任务便可使用它们。

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插件的一些示例。现在,所有人都可以提供自定义格式或任何充满想象的方式转换文档。得益于强大的框架,其直观易用,且对项目毫无破坏性。如果你对插件开发感兴趣,请查看开发人员指南

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

发表评论

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