此文档页面特定于 Scala 3，并且可能涵盖 Scala 2 中不可用的新概念。除非另有说明，此页面中的所有代码示例都假定你正在使用 Scala 3。
本章介绍如何正确编写文档字符串以及如何使用 scaladoc 的所有可用特性。由于很多内容与旧 scaladoc 相同，因此某些部分是从 此文章 中重新使用的
Scaladoc 使用附加特性扩展 Markdown，例如链接到 API 定义。这可以从静态文档和博客文章中使用，以提供混合内容。
在何处放置文档字符串
Scaladoc 注释位于它们在特殊注释块中涉及的项之前，该注释块以 /** 开头，以 */ 结尾，如下所示
/** Start the comment here
* and use the left star followed by a
* white space on every line.
*
* Even on empty paragraph-break lines.
*
* Note that the * on each line is aligned
* with the second * in /** so that the
* left margin is on the same column on the
* first line and on subsequent ones.
*
* Close the comment with *\/
*
* If you use Scaladoc tags (@param, @group, etc.),
* remember to put them at separate lines with nothing preceding.
*
* For example:
*
* Calculate the square of the given number
*
* @param d the Double to square
* @return the result of squaring d
*/
def square(d: Double): Double = d * d
在上面的示例中，此 Scaladoc 注释与方法 square 相关联，因为它在源代码中位于其正前方。
Scaladoc 注释可以位于字段、方法、类、特征、对象之前。目前，scaladoc 不支持直接解决方案来记录包。有一个专门的 github 问题，你可以在其中查看问题的当前状态。
对于在 Scala 中与类本身的定义一致的类主构造函数，使用 @constructor 标记将注释定位到主构造函数文档，而不是类概述。
标记
Scaladoc 使用 @<tagname> 标记在注释中提供特定详细信息字段。这些包括
类特定标记
@constructor放在类注释中，将描述主构造函数。
方法特定标记
@return详细说明方法的返回值（每个方法一个）。
方法、构造函数和/或类标记
@throws方法或构造函数可能抛出的异常（如果有）。@param详细说明方法或构造函数的值参数，为方法/构造函数的每个参数提供一个。@tparam详细说明方法、构造函数或类的类型参数。为每个类型参数提供一个。
用法标记
@see引用其他信息来源，如外部文档链接或文档中的相关实体。@note添加预条件或后置条件的注释，或任何其他值得注意的限制或期望。@example用于提供示例代码或相关的示例文档。
成员分组标记
这些标记非常适合具有许多成员的较大类型或包。它们允许您将 Scaladoc 页面组织成不同的部分，每个部分单独显示，按照您选择的顺序显示。
默认情况下，这些标记未启用！您必须将 -groups 标志传递给 Scaladoc 才能启用它们。通常，sbt 的操作类似于
Compile / doc / scalacOptions ++= Seq(
"-groups"
)
每个部分应具有一个在所有这些标记中使用的单字标识符，如下所示 group。默认情况下，该标识符显示为该文档部分的标题，但您可以使用 @groupname 提供更长的标题。
通常，您应该在包/特性/类/对象的 Scaladoc 中放置 @groupprio（以及可选的 @groupname 和 @groupdesc），描述所有组的内容及其顺序。然后在每个成员的 Scaladoc 中放置 @group，说明它属于哪个组。
没有 @group 标记的成员将在生成的文档中列为“未分组”。
@group <group>- 将实体标记为<group>组的成员。@groupname <group> <name>- 为组提供一个可选名称。<name>在组说明之前显示为组标题。@groupdesc <group> <description>- 添加可选的描述性文本以在组名称下方显示。支持多行格式化文本。@groupprio <group> <priority>- 控制组在页面上的顺序。默认为 0。未分组元素的隐式优先级为 1000。使用 0 到 999 之间的值来设置相对于其他组的相对位置。较低的值将出现在较高值之前。
其他标记
@author为以下实体提供作者信息@version此实体所属的系统或 API 的版本。@since类似于@version，但定义了此实体首次定义的系统或 API。@deprecated将实体标记为已弃用，同时提供应使用的替换实现以及此实体被弃用的版本/日期。@syntax <name>允许您更改文档字符串的解析器。默认语法为 markdown，但您可以使用此指令更改它。当前可用的语法是markdown或wiki，例如@syntax wiki
宏
@define <name> <definition>允许在同一源文件中的其他 Scaladoc 注释中使用 $name，这些注释将扩展为<definition>的内容。
如果当前继承级别中未提供实体的注释，但为继承层次结构中较高级别的重写实体提供了注释，则将使用超类的注释。
同样，如果省略了 @param、@tparam、@return 和其他实体标记，但可以从超类中获取，则将使用这些注释。
显式
对于显式注释继承，请使用 @inheritdoc 标记。
标记
Scaladoc 提供了两个语法解析器：markdown（默认）或 wikidoc。仍然可以在 Scaladoc 中嵌入 HTML 标记（如 Javadoc），但大多数情况下没有必要，因为可以使用标记。
Markdown
Markdown 使用 commonmark 风格，并带有两个自定义扩展
wikidoc链接，便于引用wikidoc代码块，带有大括号语法
Wikidoc
Wikidoc 是用于 scala2 scaladoc 的语法。由于许多现有源代码，它受到支持，但是不建议在新的项目中使用它。可以使用标志 -comment-syntax wiki 在全局范围内切换 wikis 语法，或在文档字符串中使用 @syntax wiki 指令。
一些可用的标准标记
`monospace`
''italic text''
'''bold text'''
__underline__
^superscript^
,,subscript,,
[[entity link]], e.g. [[scala.collection.Seq]]
[[https://external.link External Link]], e.g. [[https://scala-lang.org.cn Scala Language Site]]
有关 wiki 链接的更多信息，请参阅此 章节
其他格式说明
- 段落以一个（或多个）空行开头。注释边距中的
*有效（并且应该包括），但否则该行应该是空白的。 - 标题用周围的
=字符定义，更多的=表示子标题。例如，=Heading=、==Sub-Heading==等。 - 列表块是一系列具有相同样式和级别的列表项，没有其他块样式的干扰。无序列表可以使用
-加项目符号，有序列表可以使用1.、i.、I.或a.表示各种编号样式。在这两种情况下，前面必须有额外的空格，更多的空格会形成一个子级别。
列表块的标记如下所示
/** Here is an unordered list:
*
* - First item
* - Second item
* - Sub-item to the second
* - Another sub-item
* - Third item
*
* Here is an ordered list:
*
* 1. First numbered item
* 1. Second numbered item
* i. Sub-item to the second
* i. Another sub-item
* 1. Third item
*/
编写 Scaladoc 注释的一般说明
简洁很好！快速切入正题，人们在您的文档上花费的时间有限，请明智地使用它。省略不必要的单词。优先返回 X 而不是此方法返回 X，并执行 X、Y 和 Z 而不是此方法执行 X、Y 和 Z。DRY - 不要重复自己。避免在 @return 标记和其他形式的重复注释中重复方法描述。
有关编写 Scaladoc 的更多详细信息
有关格式和样式建议的更多信息，请参阅 Scala-lang scaladoc 样式指南。
链接到 API
Scaladoc 允许使用 Wiki 样式链接链接到 API 文档。链接到 scala.collection.immutable.List 与 [[scala.collection.immutable.List]] 一样简单。有关确切语法的更多信息，请参阅 文档注释文档。