Kotlin 注释

在 Kotlin 中，注释是一种用于解释代码功能和提供文档的工具。注释不会被编译器处理，因此不会影响代码的执行。程序员可以使用不同类型的注释来记录代码的目的、实现细节、函数参数、算法说明等。

Kotlin 支持三种类型的注释：

1. 单行注释

单行注释以 // 开头，并在同一行中提供说明。例如：

// 这是一个单行注释
val name = "John" // 这是一个变量赋值

2. 块注释

块注释以 /* 开头和 */ 结尾，可以跨越多行。块注释常用于注释大段的代码或多行说明。例如：

/*
这是一个块注释，用于说明以下代码的功能。
这里使用了一个递归函数来计算阶乘。
*/
fun factorial(n: Int): Int {
    if (n == 0) return 1
    return n * factorial(n - 1)
}

3. 文档注释

文档注释是一种特殊的注释，用于生成 API 文档。文档注释以 /** 开头和 */ 结尾，可以包含多行描述和标签。标签可以提供参数、返回值、异常等详细信息。例如：

/**
 * 这是一个计算阶乘的函数。
 *
 * @param n 非负整数，表示阶乘的数字
 * @return 阶乘的结果
 * @throws IllegalArgumentException 如果输入的数字小于零
 */
fun factorial(n: Int): Int {
    if (n < 0) {
        throw IllegalArgumentException("n 不能小于零")
    }

    if (n == 0) return 1
    return n * factorial(n - 1)
}

文档注释可以使用标签指定更多的信息，一些常用的标签包括：

• @param：描述函数参数的含义和用法
• @return：描述函数的返回值
• @throws：描述可能抛出的异常
• @see：引用其他相关的函数或类
• @sample：提供一个示例用法

除了标签之外，文档注释还可以使用 markdown 格式来提供更丰富的文档内容，例如：

/**
 * 这是一个示例函数，它演示了使用 markdown 格式的文档注释。
 *
 * - 列表项1
 * - 列表项2
 *
 * **加粗文本**
 *
 * [链接到其他函数](#otherFunction)
 *
 * ```
 * val result = exampleFunction()
 * ```
 *
 * @see [otherFunction]
 */
fun exampleFunction() {
    // 函数实现
}

fun otherFunction() {
    // 其他函数实现
}

以上是 Kotlin 中常用的注释类型和用法。注释能够提高代码的可读性和可维护性，同时也方便生成文档和帮助其他开发者理解和使用你的代码。