Как вы документируете аргументы функции?

Question

rustdoc позволяет документировать структуры поля и варианты перечислений путем включения DOc комментарий выше каждой строки:

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

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

Они будут отображаться с красивым форматированием в HTML, порожденного rustdoc. Тем не менее, я не видел каких-либо способов создания аналогичных хорошо отформатированных документов для аргументов функции. Есть ли «официальный» способ документировать их или вам просто нужно описать их свободную форму в разделе основной документации функции?

Answer 1

Я видел следующий стиль, используемый в некоторых примерах:

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

До сих пор он работает нормально для меня тоже.

Answer 2

Есть ли «официальный» способ документировать их

Существует в настоящее время не является официальным способом документирования аргументов.