链接文档

此文档页面特定于 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) vs [[definition]] 迄今为止，文档中的大多数链接都是无名的。应该很明显如何编写它们。
2. 本地成员查找与 URL 片段冲突：[](#field) vs [[#field]]
3. 重载解析与 MD 语法冲突：[](meth(Int)) vs [[meth(Int)]]
4. 现在我们有了链接语法的解析器，我们可以允许链接内部有空格（在 Scaladoc 中需要使用斜杠转义空格），但这在 Markdown 中不会被识别为链接：[](meth(Int, Float)) vs [[meth(Int, Float)]]

这些都没有使使用标准 Markdown 链接语法完全不可能，但它们使它比必要时更笨拙和丑陋。最重要的是，Markdown 链接语法甚至没有节省任何字符。