注释与文档注释

// 之后到行尾是注释。/* ... */ 是块注释，可以嵌套：

/* 外层
   /* 内层 */
   外层继续 */

块注释没有闭合时会报 unterminated block comment，并指出起始位置；它不会把文件剩下的内容静默当成注释。

块注释里还有一条额外规则：如果 // 是一行中第一个非空白内容，这一行剩下的部分全部按文本处理，其中的 */ 不再闭合注释：

/* 暂时保留旧实现
   // let cached = slow_lookup(key); */
   这一行仍然在注释里
*/

这条规则是为了注释掉本身带 */ 的代码。// 出现在一行中间时没有这个效果，它后面的 */ 照常收尾——下面这段注释在第一个 */ 处就结束了：

/* 行内的 // 不保护后面的 */ fun main() { }

文档注释

写在声明前面的 /// 或 /** ... */ 是该声明的文档：

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

文件或模块级的说明用 //! 或 /*! ... */，通常写在文件开头：

//! 几何工具。

/*! 块形式同样有效。 */

结构体字段、枚举变体这类不能单独写前置注释的位置，可以在同一行末尾用 //<：

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

//< 附着到它前面的节点。///< 不是行尾形式，它按 /// 处理并附着到后面的节点。普通 // 永远只是注释，不会成为文档。

文档注释不生成代码，也不参与类型检查。读它的是编辑器的悬停和签名帮助，以及 clue doc 生成的 HTML 文档；两处都按 Markdown 渲染标题、列表和代码围栏。