注释¶

Lumos 支持单行注释和多行注释，使用方式与 C 语言类似。

// 这是一个单行注释
/* 这是一个
   多行注释 */

单行注释¶

单行注释以 // 或连续更多的 / 开头，直到行尾结束。

注意：最后一个 / 之后必须至少有一个空白字符（例如空格或制表符），否则会导致编译错误。
//这是一个无效的注释，编译错误
// 这是一个有效的注释，编译通过
//  这是一个有效的注释，编译通过

多行注释以 /* 开头，以 */ 结尾，或首尾同时连续使用多个 *。

注意：首部最后一个 * 之后和尾部第一个 * 之前应至少包含一个空白字符（例如空格或制表符），否则会导致编译错误。
/*这是一个无效的注释，编译错误*/
/* 这是一个有效的注释，编译通过 */
/*  这是一个有效的注释，编译通过  */

多行注释不得嵌套。

对代码内容的注释会被自动推断为文档注释，编译器会将其与被注释的代码元素关联起来，并在生成文档时使用。

连续的单行注释会被合并为一个文档注释，连续的多行注释不会被合并。

/// 这是一个示例函数
///
/// 它没有任何参数，返回类型为 `unit`
fun example_func() -> unit {
    // 函数体
}

/**
 * 这是一个示例函数
 *
 * 它没有任何参数，返回类型为 `unit`
 **/
fun example_func() -> unit {
    // 函数体
}

在文件开头的注释被视为对文件的整体说明，而不是对某个特定代码元素的描述。

也可以在文件夹下建立一个 README.md 文件来为该文件夹中的所有代码提供文档说明，或为单独文件建立一个同名的 Markdown 文件来为该文件中的所有代码提供文档说明。

dir/
    README.md  # 为整个 dir 文件夹中的代码提供文档说明
    file.lm
    file.md    # 为 file.lumos 中的代码提供文档说明

README.md 不区分大小写且不允许文件重复。

文档注释默认被解析为一种 Markdown 变体，支持以下语法：

##、###、#### 等标题，并且必须从二级标题开始，不得跳级
- 一级标题 # 使用被注释的代码自动生成，若文档注释中包含一级标题，则会导致报错
- 实际文档生成工具可能会将所有标题自动增加几个层级，比如从三级标题开始
- 作为无序列表，+ 作为有序列表
代码块（使用三个反引号 ``` 包裹）
行内代码（使用单个反引号 ` 包裹）
粗体（使用 ** 包裹）和斜体（使用 * 包裹）

文档注释解析中出现的错误不应当影响代码的正常编译（除非有自定义流程用到了文档内容），但会导致文档生成失败，并且应当在编辑器中显示为错误而非警告。