注释与文档

注释与文档#

注释#

在代码内部使用 // 编写普通注释：

// Explain why this branch exists.
let retries = 3

你也会经常在顶层代码块开头看到 ///|。它是一条空的文档注释行，用来显式分隔顶层条目。这对于当前的文档工具链很重要，也能为未来的缓存和其他工具用途保留清晰的顶层块边界。实际使用中，///| 不仅适用于文档源码，在普通的 MoonBit 代码里也很有用。

文档注释#

文档注释使用 ///，逐行写在 fn、let、enum、struct、type 等顶层条目前面。文档注释内容使用 Markdown 编写。

/// 返回一个新数组，其中元素被反转。
fn[T] reverse(xs : Array[T]) -> Array[T] {
  ...
}

文档注释中的 Markdown 代码块如果标记为 mbt check，就会被视作文档测试；moon check 和 moon test 会自动检查并运行这些测试，从而保证文档注释中的示例始终是最新的。需要测试块时，请将代码包在 test { .. } 中：

/// 将一个整数加一，
///
/// 示例：
/// ```mbt check
/// test {
///   inspect(incr(41), content="42")
/// }
/// ```
pub fn incr(x : Int) -> Int {
  x + 1
}

如果想要阻止一段代码被当作文档测试，只需要在它的 markdown 代码块上标记一个 mbt check 以外的语言名字：

/// `c_incr(x)` 等价于下面的 C 代码：
/// ```c
/// x++
/// ```
pub fn c_incr(x : Ref[Int]) -> Int {
  let old = x.val
  x.val += 1
  old
}

目前，文档测试都是 黑盒测试。所以私有定义目前不能有文档测试。

文学化 .mbt.md 文件#

MoonBit 也支持以 .mbt.md 结尾的文学化 Markdown 文件。这些文件既可以作为包内的可检查文档，也可以作为 moon check 和 moon test 的独立单文件输入。

对于独立文件，运行：

moon check README.mbt.md
moon test README.mbt.md

在项目内部，请继续使用包级别的 moon check 和 moon test 命令。

代码块的语言标记决定了每个代码块会如何处理：

  • mbt：会编译其中的 MoonBit 代码，但不会创建测试入口。

  • mbt check：MoonBit 文档测试代码。需要断言时，请在代码块内部使用 test { .. } 或 async test。

  • mbt nocheck：展示 MoonBit 代码，但不编译也不测试。

  • moonbit：普通的文档展示代码块，不会被编译或测试。

例如：

```mbt nocheck
///|
fn helper() -> Int {
  42
}
```

```mbt check
///|
test "forty two" {
  inspect(40 + 2, content="42")
}
```

```mbt nocheck
///|
fn native_only() -> Unit {
  ...
}
```

独立的 .mbt.md 文件也可以声明 front matter 来指定导入或目标后端：

---
moonbit:
  import:
    - path: moonbitlang/core/ref
      alias: ref
  backend:
    native
---

```mbt check
fn answer() -> Int {
  let cell : @ref.Ref[Int] = { val: 41 }
  cell.val + 1
}

///|
test "answer" {
  inspect(answer(), content="42")
}
```

当你想显式指定该文件可以直接导入哪些包时，使用 moonbit.import。当你只想声明模块依赖并让 Moon 自动合成导入时，使用 moonbit.deps。

目录