注释

注释给代码补充人类可读的说明，帮助读者理解意图。编译器会忽略注释的内容。

行注释

Riddle 使用 // 行注释，从 // 到行尾的内容都会被忽略：

// 计算两点间距离的平方
fun distance_squared(x: i32, y: i32) -> i32 {
    x * x + y * y // 尾随注释
}

块注释

块注释从 /* 开始，到匹配的 */ 结束，并支持嵌套：

/* 外层说明
   /* 内层说明 */
   外层继续 */
fun square(x: i32) -> i32 { x * x }

块注释可以出现在表达式、类型和声明之间。未闭合的块注释会把文件剩余内容视为注释；需要保留后续代码时应补上闭合的 */。

文档注释

文档注释使用 /// 或 /** ... */ 写在声明前；也可以用 //< 在同一行记录前一个声明或字段。//! 和 /*! ... */ 用于模块或文件级说明：

//! 几何工具模块

/** 计算两点间距离的平方。 */
fun distance_squared(x: i32, y: i32) -> i32 {
    x * x + y * y
}

struct Point {
    x: i32, //< 横坐标
    y: i32, //< 纵坐标
}

只有 //< 会附着到前一个节点；普通 // 仍是普通注释，///< 仍按 /// 处理并附着到后一个节点。文档注释不参与类型检查或生成运行时代码。语法树层提供 ast::doc_comments_for_node，HIR 会保留文档注释与声明的源范围；LSP 的悬停和签名帮助会把紧邻声明的文档注释作为 Markdown 说明返回。

写普通的多行说明时，也可以继续使用多条 //：

// 该函数只在输入为非负整数时有意义。
// 需要处理负输入时，先用 `abs` 取绝对值。
fun square(x: i32) -> i32 {
    x * x
}

普通注释中的内容不参与任何编译阶段；错误码参考、LSP 悬停等能力不会自动把普通注释转换成文档。文档工具读取文档注释时仍需自行解释其文本格式。