文档

目录

文档#

文档注释#

文档注释是在顶层结构（如 fn、let、enum、struct、type）的每一行前面加上 /// 的注释。文档注释内包含 markdown 文本。

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

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

/// Increment an integer by one,
///
/// Example:
/// ```mbt check
/// test {
///   inspect(incr(41), content="42")
/// }
/// ```
pub fn incr(x : Int) -> Int {
  x + 1
}

文档测试同样适用于 .mbt.md 这样的文学化文件。对于独立文件，可以运行 moon check README.mbt.md 和 moon test README.mbt.md。在项目内请使用包级别的 moon check 和 moon test。

如果想要阻止一段代码被当作文档测试，只需要在它的 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
}

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

目录