基於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外掛的一些示例。現在，所有人都可以提供自定義格式或任何充滿想象的方式轉換文件。得益於強大的框架，其直觀易用，且對專案毫無破壞性。如果你對外掛開發感興趣，請檢視開發人員指南。