新的 Scala 版本 3 附帶文件產生器 Scaladoc 的全新實作,從頭開始改寫。在本文中,您可以找到 Scaladoc 已經或將要推出的新功能重點。有關一般參考,請參閱 Scaladoc 手冊。
新功能
Markdown 語法
Scaladoc 新版本中引入的最大變更,就是文件字串的預設語言變更。到目前為止,Scaladoc 僅支援 Wikidoc 語法。新的 Scaladoc 仍然可以剖析舊版的 Wikidoc
語法,不過 Markdown 已被選為格式化註解的主要語言。若要切換回 Wikidoc
,可以在執行 doc
任務之前傳遞一個全域旗標,或者可以透過 @syntax wiki
指令為特定註解定義它。
如需瞭解如何使用文件字串的全部功能,請查看 Scaladoc 文件字串
靜態網站
Scaladoc 也提供一個簡單的方式,用於為文件和部落格文章建立靜態網站,其方式類似於 Jekyll。有了這個功能,你可以將文件儲存在與產生的 Scaladoc API 並排的位置,這非常方便。
如需瞭解如何設定靜態網站的產生,請查看 靜態文件 章節
部落格文章
部落格文章是靜態網站的一種特定類型。在 Scaladoc 手冊中,你可以找到關於如何使用 部落格文章 的其他資訊。
社群連結
此外,Scaladoc 提供一個簡單的方式,用於設定你的 社群媒體連結,例如 Twitter 或 Discord。
實驗性功能
以下功能目前 (2021 年 5 月) 尚不穩定,無法與 scaladoc 一起發布,不過我們很樂意聽取你的意見回饋。每個功能在 scala-lang 貢獻者網站上都有自己的執行緒,你可以在那裡分享你的意見。
片段編譯
Scaladoc 的實驗性功能之一是片段編譯器。這個工具可讓你編譯附加到文件字串的片段,以檢查它們是否實際上按預期執行,例如正確編譯。這個功能與 tut
或 mdoc
工具非常類似,但會與 Scaladoc 一起提供,以便於設定和整合到你的專案中。讓片段具有互動性(例如讓使用者在瀏覽器中編輯和編譯它們)正在考慮中,不過這個功能目前不在範圍內。
展示
- 隱藏程式碼
- 宣告編譯錯誤
- 片段包含
如需更多資訊,請參閱 指南,或追蹤這個 Scala 貢獻者討論串
基於類型的搜尋
透過函式的符號名稱搜尋函式可能會很耗時。因此,新的 scaladoc 允許您透過類型搜尋方法和欄位。
因此,對於宣告
extension [T](arr: IArray[T]) def span(p: T => Boolean): (IArray[T], IArray[T]) = ...
我們可以搜尋 span
,也可以搜尋 IArray[A] => (A => Boolean) => (IArray[A], IArray[A])
。
若要使用此功能,只要在 scaladoc 搜尋欄位中輸入您要尋找的函式簽章即可。以下是它的運作方式
此功能由 Inkuire 搜尋引擎提供,適用於 Scala 3 和 Kotlin。若要了解此功能的最新開發進度,請追蹤 Inkuire 儲存庫。
如需更多資訊,請參閱 指南
請注意,此功能仍處於開發階段,因此可能會大幅變更。如果您遇到錯誤或有改進的想法,請隨時在 Inkuire 或 scala3 建立問題。