rust 文档注释书写规范

981377660LMT commented 6 months ago

文档注释是用于生成代码文档的重要部分，因此编写规范的文档注释可以提高代码的可读性和可维护性。以下是一些常见的文档注释规范和最佳实践：

使用 /// 开始注释：文档注释应该以三个斜杠 /// 开始，紧跟在要注释的项（函数、结构体、模块等）之前。
使用 Markdown 格式：文档注释支持 Markdown 格式，可以使用 Markdown 语法来添加标题、列表、链接、代码块等。这样可以使文档更具可读性和格式化。
使用标题：使用 # 标题来表示不同的部分，例如描述、用法、参数、返回值等。使用适当的标题层级来组织文档。
描述项的用途和功能：在文档注释的开始部分，提供对项的简要描述和功能的解释。这有助于其他开发者快速了解项的用途和作用。
描述参数和返回值：对于函数或方法，使用列表或表格来描述参数和返回值。对于每个参数，提供名称、类型和描述。对于返回值，提供类型和描述。
描述错误处理：如果函数可能引发错误或返回错误类型，描述错误的类型、原因和处理方式。这有助于其他开发者了解如何处理潜在的错误情况。
提供示例代码：在文档注释中提供示例代码，以演示如何使用该项。示例代码应该简洁、清晰，并突出显示项的用法和功能。

需要注意的是，文档注释应该是有益的、准确的和易于理解的。它们应该提供足够的信息，以便其他开发者可以理解和使用代码。

为了生成代码文档，你可以使用 cargo doc 命令。它会根据代码中的文档注释生成HTML格式的文档，并将其保存在 target/doc 目录下。

981377660LMT commented 6 months ago

/// This function divides two numbers.
///
/// # Arguments
///
/// * `a` - The dividend
/// * `b` - The divisor
///
/// # Returns
///
/// Returns the result of the division.
///
/// # Errors
///
/// Returns an `Err` variant if the divisor is zero.
///
/// # Panics
///
/// Panics if the dividend is negative.
///
/// # Example
///
/// ```
/// let result = divide_numbers(10, 2);
/// assert_eq!(result, Ok(5));
///
/// let error_result = divide_numbers(10, 0);
/// assert!(error_result.is_err());
/// ```
fn divide_numbers(a: i32, b: i32) -> Result<i32, &'static str> {
    if a < 0 {
        panic!("Dividend cannot be negative");
    }

    if b == 0 {
        return Err("Cannot divide by zero");
    }

    Ok(a / b)
}

981377660LMT commented 6 months ago

link 使用：

/// This is a test function.
///
/// Link to [rust_doc_markdown].
///
/// Highlight `rust_doc_markdown`.
///
/// Highlight link [`rust_doc_markdown`].
///
/// link to rust site [Rust](https://www.rust-lang.org/).
///
/// [`truncate`], [`resize`].
///
/// [`truncate`]: Vec::truncate
///
/// # Example
/// ```
/// rust_doc_markdown();
/// ```
/// # Time complexity
///
/// Takes *O*([`Vec::len`]) time.
fn rust_doc_markdown() {}

981377660LMT / ts

rust 文档注释书写规范 #492