Scaladoc

設定

語言
    此文件頁面專門針對 Scala 3，可能涵蓋 Scala 2 中沒有的新概念。除非另有說明，此頁面中的所有程式碼範例都假設您使用的是 Scala 3。

    此章節列出呼叫 scaladoc 時可使用的組態選項。部分在此顯示的資訊可透過使用 -help 標記呼叫 scaladoc 來取得。

    與 Scala 2 的 scaladoc 相容性

    Scaladoc 已從頭開始重新編寫，部分功能在新內容中已變得無用。如果您想了解與舊 scaladoc 標記的相容性目前狀態，您可以前往此問題追蹤 進度。

    提供設定

    提供 scaladoc 設定作為命令列引數，例如 scaladoc -d output -project my-project target/scala-3.0.0-RC2/classes。如果從 sbt 呼叫，請分別更新 Compile / doc / scalacOptions 和 Compile / doc / target 的值，例如

    Compile / doc / target := file("output"),
Compile / doc / scalacOptions ++= Seq("-project", "my-project"),

    所有可用設定的概觀

    -project

    專案名稱。提供與 Scala2 別名相容，使用 -doc-title

    -project-version

    專案的目前版本，顯示在左上角。提供與 Scala2 別名相容，使用 -doc-version

    出現在左上角的專案標誌。深色主題的標誌可以透過後綴 _dark 提供。如果標誌為 mylogo.png，則假設深色主題為 mylogo_dark.png。若要與使用 -doc-logo 的 Scala2 別名相容

    -project-footer

    出現在頁尾區段的字串訊息。若要與使用 -doc-footer 的 Scala2 別名相容

    -comment-syntax

    用於剖析註解的樣式語言。目前我們支援兩種語法：markdown 或 wiki 如果未設定，scaladoc 預設為 markdown

    -revision

    用於建置專案的版本（分支或參照）。對於 sourcelinks 很實用，可以防止它們總是指向最新的 main，而 main 會變更。

    -source-links

    Source links 提供文件和程式碼儲存庫中檔案之間的對應。

    Source links 範例：-source-links:docs=github://scala/scala3/main#docs

    可接受的格式

    <sub-path>=<source-link>

    其中 <source-link> 是下列其中一項

    • github://<organization>/<repository>[/revision][#subpath] 會符合 https://github.com/$organization/$repository/[blob|edit]/$revision[/$subpath]/$filePath[$lineNumber]，如果未提供版本，則需要將版本指定為 scaladoc 的引數
    • gitlab://<organization>/<repository> 會符合 https://gitlab.com/$organization/$repository/-/[blob|edit]/$revision[/$subpath]/$filePath[$lineNumber]，如果未提供版本，則需要將版本指定為 scaladoc 的引數
    • <scaladoc-template>

    <scaladoc-template> 是舊 scaladoc 中 doc-source-url 參數的格式。注意：我們只支援 €{FILE_PATH_EXT}、€{TPL_NAME}、€{FILE_EXT}、€{FILE_PATH} 和 €{FILE_LINE} 模式。

    範本只能由 <sub-path> 表示的路徑前綴所定義的來源子集定義。在這種情況下，範本中使用的路徑將相對於 <sub-path>

    -external-mappings

    符合類別路徑條目和外部文件的正規表示式之間的對應。

    範例外部對應：-external-mappings:.*scala.*::scaladoc3::https://scala-lang.org/api/3.x/,.*java.*::javadoc::https://docs.oracle.com/javase/8/docs/api/

    對應的格式為 <regex>::[scaladoc3|scaladoc|javadoc]::<path>。你可以提供多個對應，並以逗號分隔，如範例所示。

    -social-links

    連結到社群網站。例如

    -social-links:github::https://github.com/scala/scala3,discord::https://discord.com/invite/scala,twitter::https://twitter.com/scala_lang

    有效值格式為：[github|twitter|gitter|discord]::link。Scaladoc 也支援 custom::link::white_icon_name::black_icon_name。在此情況下，圖示必須存在於 images/ 目錄中。

    -skip-by-id

    產生文件時要略過的套件或頂層類別識別碼。

    -skip-by-regex

    產生文件時要略過的套件或頂層類別完全限定名稱相符的正規表示式。

    -doc-root-content

    應從中匯入根套件文件的文件。

    -author

    預設情況下，在文件字串中加入作者 @author 名字 姓氏 時，不會包含在產生的 HTML 文件中。如果你想明確標示類別的作者，請使用這個 flag 執行 scaladoc。

    -groups

    將類似的函式群組在一起（根據 @group 註解）

    -private

    顯示所有類型和成員。除非指定，否則只顯示公開和受保護的類型和成員。

    -doc-canonical-base-url

    用作前綴的基本 URL，並將 canonical URL 新增到所有頁面。搜尋引擎可能會使用 canonical URL 來選擇你希望人們在搜尋結果中看到的 URL。如果未設定，則不會產生任何 canonical URL。

    -siteroot

    包含要產生文件的靜態檔案的目錄。預設目錄為 ./docs

    -no-link-warnings

    抑制成員查詢中連結不明確或不正確的警告。不會影響資產等連結不正確的警告。

    -versions-dictionary-url

    指向包含字典的 JSON 文件的 URL：版本標籤 -> 文件位置。JSON 檔案有一個屬性 versions，其中包含字典，將文件特定版本的標籤與指向其 index.html 的 URL 關聯。對於維護不同文件版本的函式庫很有用。

    範例 JSON 檔案

    {
  "versions": {
    "3.0.x": "https://dotty.epfl.ch/3.0.x/docs/index.html",
    "Nightly": "https://dotty.epfl.ch/docs/index.html"
  }
}
    -snippet-compiler

    片段編譯器參數提供一種設定片段類型檢查的方法。

    此設定接受格式為：args := arg{,args} arg := [path=]flag 的參數清單，其中 path 是片段所在的來源檔案路徑的前綴，而 flag 是片段將被類型檢查的模式。

    如果路徑不存在，則參數將用作所有不匹配路徑的預設值。

    可用的標記

    • compile - 啟用片段檢查。
    • nocompile - 停用片段檢查。
    • fail - 啟用片段檢查，斷言片段無法編譯。

    fail 標記適用於片段，表示某些動作最終會在編譯期間失敗，例如 Opaques 頁面

    範例用法

    -snippet-compiler:my/path/nc=nocompile,my/path/f=fail,compile

    表示

    • 目錄 my/path/nc 下所有檔案中的片段都不應編譯
    • 目錄 my/path/f 下所有檔案中的片段應在編譯期間失敗
    • 所有其他片段都應成功編譯
    -scastie-configuration

    定義 Scastie 片段的其他 sbt 組態。例如，當您將外部函式庫匯入片段時，您需要新增相關依賴項。

    "-scastie-configuration", """libraryDependencies += "org.apache.commons" % "commons-lang3" % "3.12.0""""
    -dynamic-side-menu

    使用 JavaScript 在瀏覽器中動態產生側邊選單（左側專案結構的樹狀概觀），而不是將其嵌入每個 HTML 檔案中。這可以大幅減少輸出的 HTML 檔案大小。建議用於超過 1000 個頁面的專案。如需更多資訊，請參閱 議題 18543。

    -Ysnippet-compiler-debug

    設定此選項會讓片段編譯器在編譯片段時列印片段（包裝後）。

    -Ydocument-synthetic-types

    將提供內建類型（例如 Any、Nothing）文件說明的頁面納入文件。此設定僅對標準函式庫有用，因為 Scala 3 的 scaladoc 依賴於 TASTy 檔案，但我們無法為內建類型提供這些檔案，因為它們已嵌入編譯器中。所有其他使用者不應關注此設定。

    ← 上一頁

    此頁面的貢獻者

    內容
    此頁面有問題嗎？
         請協助我們修復它！