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) {}

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

PS 这也有问题。
PS 检查改进的 rustdoc链接和1.48中的搜索别名 。

Answer 2

是否有“官方”的方式来记录它们

目前没有正式的方法来记录论点。

Answer 3

根据 rust 文档，函数文档的格式如下：

#![crate_name = "doc"]

/// A human being is represented here
pub struct Person {
    /// A person must have a name, no matter how much Juliet may hate it
    name: String,
}

impl Person {
    /// Returns a person with the name given them
    ///
    /// # Arguments
    ///
    /// * `name` - A string slice that holds the name of the person
    ///
    /// # Examples
    ///
    /// ```
    /// // You can have rust code between fences inside the comments
    /// // If you pass --test to `rustdoc`, it will even test it for you!
    /// use doc::Person;
    /// let person = Person::new("name");
    /// ```
    pub fn new(name: &str) -> Person {
        Person {
            name: name.to_string(),
        }
    }

    /// Gives a friendly hello!
    ///
    /// Says "Hello, [name]" to the `Person` it is called on.
    pub fn hello(& self) {
        println!("Hello, {}!", self.name);
    }
}

fn main() {
    let john = Person::new("John");

    john.hello();
}