Kotlin 1.4的Dokaa Alpha版

kotliner發表於2020-09-21

我們已經在Kotlin 1.4上釋出了Dokka(Alpha)! 該發行版保證Dokka的版本與Kotlin編譯器的最新穩定版本一致。 它著重於減少Dokka在最普遍場景下(包括Kotlin多平臺專案)的配置項,能花費更少時間編寫Dokka配置,意味著能有更多的時間來編寫Kotlin文件!

img

我們在Kotlin 1.4.0-RC上釋出了Dokka,而其中我們重新設計了文件引擎的大部分,並引入了許多新特性和改進,例如新的HTML格式多模組專案擴充套件性

自那時起,我們從社群中收到了很多寶貴的反饋意見——從bug修復到多平臺專案中更優的源集分組——我們合併到該版中。 下面來看看!

簡化的Gradle外掛

Dokka的這個版本,我們在保證支援高階配置情況下,盡力讓Gradle外掛更易於使用。實際上從現在開始,大多數專案通過Dokka生成文件都不需要任何手動配置!只需新增Dokka Gradle外掛便足以涵蓋build.gradle.kts中常見情況:

有關文件生成所需所有資訊(包括源集的資訊),將自動與Kotlin Gradle外掛保持同步。 已註冊或Kotlin監視的每個源集也將自動應用Dokka中的深度配置。

剩下要做的就是執行Dokka任務 例如dokkaHtmldokkaJavadoc)以生成專案的文件。當然,你仍可以通過進一步的配置讓Dokka滿足特定的要求,或者使用高階功能。

我們希望消除大量需要手動的配置,完善”自動配置”機制並使其更加直觀,我們可以讓使用者更輕鬆地開始使用Dokka生成文件。

多平臺

上一節介紹的預設配置也適用於多平臺專案。只需應用Dokka Gradle外掛,所有平臺特定的源集將自動與Kotlin模組同步。對於大多數專案,不再需要在Dokka中註冊其他源集,這意味著可以從配置檔案中刪除冗餘資訊。 為了簡單地控制不同平臺的處理方式,我們還引入了一種直接的方法來合併多個源集。

合併源集

預設情況下,Dokka會在專案中為每個源集顯示一個“氣泡”(平臺標記),這是一個將文件過濾為指定目標API的快捷方法。但如果在一個有大量源集的專案中,例如面向多個native目標的Kotlin多平臺專案,那麼該預覽會很快變得混亂。例如這個kotlinx-coroutines的示例:

img

之前,需要複雜的配置才能將這些相關源集組合到單個“氣泡”中,但反過來看又在專案構建檔案中引入了不必要的複雜性。

因為我們看到社群及Kotlin官方的專案都對這種分組功能的強烈需求,所以我們引入了一種更新更為簡化的機制來解決源集的合併。表示相同平臺(通用,JVM,JS或Native)且具有相同displayName的所有源集都將合併到相同的“氣泡”中。

例如,要將所有Native源集歸到“Native氣泡”下,你可以在build.gradle.kts中輕易地應用如下配置:

重新生成文件後,你將看到更加簡潔的源集“氣泡”列表:

img

我們希望這種合併源集的支援能簡化你的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體驗最好的文件工具!

相關文章