IntelliJ IDEA 现已支持 Scaladoc 使用 Markdown 语法
本篇博文也有 YouTube 视频版本。
在 Scala 2 中，Scaladoc 使用 Wikidoc 语法，该语法拥有模板、类别和元数据等高级功能。这些功能对于组织和构建大量文档很有用，但在代码注释中却很少使用。另一方面，Markdown 提供了更简单、更具可读性的语法；在许多情况下，您可以直接阅读其原始文本而没有任何问题。Markdown 也更加流行，并且已广泛用于 README 文件和其他文档文件中，因此在 Scaladoc 中使用它也是顺理成章的。
关于这一点的最好例子大概是 Markdown 中表格的编写方式。
如您所见，表格的原始版本只是一个由 ASCII 字符构成的表格，至少在数据简短简单的情况下，无需渲染即可阅读。
在 Scala 3 中，同时支持 Wikidoc 和 Markdown，但 Markdown 已被选为默认语法。换句话说，如果您向类、方法或字段声明添加文档注释（即以斜杠和两个星号开头的注释，/** ... */），默认情况下我们将假定其使用 Markdown 格式。
Markdown 语法
在新版本中，IntelliJ Scala 插件提供了对新 Scaladoc 的支持。这意味着支持以下所有语法功能：
- 以井号 (
#) 开头的标题，以及通过在下一行用等号 (=) 给文本加下划线构成的标题。 - 较小的、“子章节”标题，使用多个井号或在下一行使用连字符 (
-)。 - 有序和无序列表 —— 除了渲染它们之外，当您编写时，Scala 插件还会自动生成新的索引和项目符号。您也可以创建子列表：渲染时，有序列表的子列表会有更深的缩进，而无序列表的子列表则会有不同的项目符号。
- 使用“大于”号 (
>) 的块引用。如果您开始编写多行引用，Scala 插件将自动为后续行生成符号。就像列表一样，您也可以编写嵌套的块引用。
|--------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------| | [LOADING...] | [LOADING...] |
- 使用星号 (
*) 或下划线 (_) 符号制作的粗体、斜体和粗斜体字体。如果您只输入一个星号或一个下划线，Scala 插件将生成另一个结束符号，您在它们之间输入的任何内容都将渲染为斜体。如果您在一侧使用两个星号或两个下划线，中间的文本将变为粗体。如果您使用三个，文本将同时渲染为斜体和粗体。 - 删除线文本也是如此，使用两个波浪号 (
~~) 制作。 - 使用
[link](text)的链接。如果您渲染它并点击它，IntelliJ IDEA 将打开您的默认 Web 浏览器并将您定向到给定的网页。 - 使用
[[name]]的代码锚点。双方括号内的文本应该是现有类、trait 等的名称。当您编写它时，Scala 插件将显示代码完成弹出窗口以帮助您找到它。渲染后，您将看到锚点像链接一样高亮显示，但是当您点击它时，Scala 插件将显示附加到它的文档注释，而不是重定向到该元素。
[LOADING...]
-
水平线，由一个空行后跟三个连字符 (
---) 组成。空行很重要，否则由连字符组成的行将被理解为子章节标题。 -
行内代码 —— 以反引号开头或使用
<code>标签。 -
多行代码块 —— 以大括号
{{{ ... }}}开头或使用反引号 "..."。 -
还有表格，我们在上面已经讨论过，但还有一点需要补充 —— 使用以下语法，您可以控制表格列内的文本对齐方式：
向后兼容性
如果您想切换回旧的 wikidoc 语法，请将 @syntax wiki 指令放在注释块末尾的指令部分。这一点很重要，因为 @syntax 指令的处理方式与 @param 和 @return 等其他指令类似，应该与它们放在一起。如果您出错并将其放在顶部或注释内部，该指令下方的所有内容都将无法渲染。
如何渲染
在 IntelliJ IDEA 中使用 Scala 插件渲染 Scaladoc 有三种方式：
- 点击第一条 Scaladoc 行左侧的装订线图标。文档将直接在编辑器中渲染。
- 将光标悬停在注释块上。将出现一个包含渲染内容的弹出窗口。
- 如果注释块附加到代码元素（例如类或方法），您可以将光标悬停在其名称上，无论它是其定义还是代码中其他位置对它的调用。这也将显示一个包含渲染内容的弹出窗口。
有关更多信息，您可以参考以下来源：
- Scaladoc | Style Guide | Scala Documentation
- Guide to Scaladoc | Baeldung on Scala
- Scaladoc for Library Authors | Scaladoc | Scala Documentation
祝开发愉快！
JetBrains Scala 团队