旋武社区

G.CMT.01 公开的 API 需要文档注释 ​

【级别】 建议

【描述】

  • 公开 API 如需返回 Result 类型的函数，则相应文档中需增加 Error 注释 解释什么场景下会返回什么样的错误类型，便于调用者处理错误。
  • 公开 API 如有发生 Panic 的可能，则相应文档中需增加 Panic 注释 解释在什么条件下会发生 Panic ，便于调用者进行预处理。
  • 公开 API 中的 Unsafe 函数或 trait ，文档中需添加 Safety 注释和相关说明 解释该函数接口的安全边界，便于调用者安全地使用。

在函数内部的 unsafe 代码块（即 unsafe {...} ）上方，不统一要求，但是建议添加 SAFETY 注 释，提升代码的可维护性。

Safety 文档注释建议包含以下内容（如果适用）：

  • 前提条件（例如，参数的有效状态是什么？） 。 失败处理（例如，什么值应该被释放？）
  • 成功处理（例如，什么值被创建或消耗？）

【正例】

Rust
use std::io;
// 符合：增加了规范的 Errors 文档注释 /// ...
/// # Errors ///
/// Will return `Err` if `filename` does not exist or the user does not have /// permission to read it.
pub fn read(filename: &str) -> io::Result<String> {
  // ...
}

// 符合：增加了规范的 Panic 注释 /// ...
/// # Panics ///
/// Will panic if y is 0
pub fn divide_by(x: i32, y: i32) -> i32 { 
  if y == 0 {
    panic!("Cannot divide by 0") 
  } else {
    x / y
  } 
}

// 符合：增加了 unsafe 下的 Safety 注释 /// ...
/// # Safety ///
/// The bytes passed in must be valid UTF-8. /// ...
pub const unsafe fn from_utf8_unchecked(v: &[u8]) -> &str {
  // SAFETY: the caller must guarantee that the bytes `v` are valid UTF-8.
  // Also relies on `&str` and `&[u8]` having the same layout.
unsafe { mem::transmute(v) } 
}