文档

文档#

文档注释#

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

/// 返回一个新数组，其中元素被反转。
///
/// # 示例
///
/// ```
/// reverse([1,2,3,4]) |> println()
/// ```
fn reverse[T](xs : Array[T]) -> Array[T] {
  ...
}

注解#

注解是文档注释中的标记。它们都采用 /// @word ... 的形式。word 表示注解的类型，后面可以跟几个 word 或字符串文字。注解通常不会影响程序的含义。未识别的注解将被报告为警告。

  • 警告注解

    函数文档注释中的警告注解将在引用这些函数时报告。这种机制是一种通用的方法，用于将函数标记为 deprecated 或 unsafe。

    它采用 @alert category "alert message..." 的形式。

    类别可以是任意标识符。它允许配置决定哪些警告是启用的或转换为错误。

    /// @alert deprecated "Use foo2 instead"
pub fn foo() -> Unit {
  ...
}

/// @alert unsafe "Div will cause an error when y is zero"
pub fn div(x : Int, y : Int) -> Int {
  ...
}

test {
  // Warning (Alert deprecated): Use foo2 instead
  foo()
  // Warning (Alert unsafe): Div will cause an error when y is zero
  div(1, 2) |> ignore
}
目录