rust - 你如何记录函数参数？

Question

rustdoc 允许您通过在每一行上方包含文档注释来记录结构字段和枚举变体:

enum Choices {
  /// The first choice.
  First,
  /// The second choice.
  Second,
}

struct Person {
  /// The person's name.
  name: String,
  /// The person's age.
  age: u8,
}

这些将以漂亮的格式显示在 rustdoc 生成的 HTML 中。但是，我还没有看到任何方法可以为函数参数制作类似的格式良好的文档。是否有一种“官方”方式来记录它们，或者您只需要在函数的主要文档部分中自由描述它们？

Answer 1

我在一些示例中看到了以下样式:

/// Brief.
///
/// Description.
/// 
/// * `foo` - Text about foo.
/// * `bar` - Text about bar.
fn function (foo: i32, bar: &str) {}

到目前为止，它对我来说也很好用。

附言还有一个 issue关于这个。
附言还要检查改进的 rustdoc 链接 和搜索别名 in 1.48 .
附言现在在 https://doc.rust-lang.org/beta/rust-by-example/meta/doc.html 有一个文档