連結文件

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

Scaladoc 的主要功能是從程式碼註解建立 API 文件。

預設情況下，程式碼註解會被理解為 Markdown，不過我們也支援 Scaladoc 的舊 Wiki 語法。

語法

定義連結

我們的定義連結語法非常接近 Scaladoc 的語法，儘管我們做了一些改善生活品質的改進。

基本語法

定義連結如下所示：[[scala.collection.immutable.List]]。

也就是說，定義連結是由 . 分隔的一系列識別碼。識別碼可以用 # 分隔，以符合 Scaladoc 相容性。

預設情況下，識別碼 id 參照命名為 id 的第一個實體（依據來源順序）。識別碼可以以 $ 結尾，這會強制它參照一個值（一個物件、一個值、一個給定的）；識別碼也可以以 ! 結尾，這會強制它參照一個類型（一個類別、一個類型別名、一個類型成員）。

連結是根據來源中的目前位置解析的。也就是說，在記錄一個類別時，連結是根據封裝類別的實體（一個套件、一個類別、一個物件）而定的；記錄定義時也適用相同的原則。

連結中的特殊字元可以用反斜線轉譯，這會讓它們變成識別碼的一部分。例如，[[scala.collection.immutable\.List]] 參照套件 scala.collection 中名為 `immutable.List` 的類別。

新語法

我們已擴充 Scaladoc 定義連結，讓它們在來源中更易於撰寫和閱讀。目標也是讓連結和 Scala 語法更接近。新功能如下

1. package 可用作參照封裝套件的前置詞範例

    package utils
    class C {
      def foo = "foo".
    }
    /** See also [[package.C]]. */
    class D {
      def bar = "bar".
    }
   

   關鍵字 package 可協助縮短連結至封裝套件的長度，並讓連結較不易受到名稱重新整理的影響。

2. this 可用作前綴來參照封裝的類別範例

    class C {
      def foo = "foo"
      /** This is not [[this.foo]], this is bar. */
      def bar = "bar"
    }
   

   在此處使用 Scala 關鍵字有助於讓連結更為熟悉，並協助連結在類別名稱變更後仍能繼續使用。

3. 反引號可作為識別碼範例的跳脫字元

    def `([.abusive.])` = ???
    /** TODO: Figure out what [[`([.abusive.])`]] is. */
    def foo = `([.abusive.])`
   

   先前 (2.x 版本)，Scaladoc 需要反斜線跳脫才能參照此類識別碼。現在 (3.x 版本)，Scaladoc 允許使用熟悉的 Scala 反引號引號。

為何保留 Wiki 語法作為連結？

我們保留 Wiki 語法作為文件連結，而不是重複使用 Markdown 語法，有幾個原因。這些原因是

1. Markdown 中的無名連結很醜：[](definition) 相較於 [[definition]] 大多數文件中的連結都是無名的。撰寫連結的方式應該很明顯。
2. 區域成員查詢與 URL 片段衝突：[](#field) 相較於 [[#field]]
3. 過載解析與 MD 語法衝突：[](meth(Int)) 相較於 [[meth(Int)]]
4. 現在我們有了連結語法的剖析器，我們可以在其中允許空格 (在 Scaladoc 中需要使用斜線跳脫這些空格)，但 Markdown 中不會將其辨識為連結：[](meth(Int, Float)) 相較於 [[meth(Int, Float)]]

這些都不會完全無法使用標準 Markdown 連結語法，但它們會讓它變得比它需要時更尷尬且醜陋。最重要的是，Markdown 連結語法甚至不會儲存任何字元。