Kotlin 1.4的Dokaa Alpha版

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

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

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

簡化的Gradle外掛

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

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

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

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

多平臺

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

合併源集

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

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

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

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

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

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