How do you document function arguments?

Question

rustdoc allows you to document struct fields and enum variants by including a doc comment above each line:

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

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

These will show up with nice formatting in the HTML generated by rustdoc. However, I haven't seen any way of making similar nicely-formatted documents for function arguments. Is there an "official" way to document them or do you just have to describe them freeform in the function's main documentation section?

FWIW, I prefer to leverage the type system. Instead of saying "This u8 must be a power of 2 or prime", make a `PowerOfTwoOrPrime` newtype with an appropriate constructor. — Shepmaster, May 03 '15 at 02:51
No syntax for that nor are guidelines/conventions established. — bluss, May 03 '15 at 08:08

ArtemGr · Answer 1 · 2023-01-03T06:18:30.610

43

I've seen the following style used in some of the examples:

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

So far it's working fine for me too.

P.S. There's also an issue on this.
P.S. Check also the improved rustdoc linking and the search aliases in 1.48.
P.S. There's now a docu at https://doc.rust-lang.org/beta/rust-by-example/meta/doc.html

edited Jan 03 '23 at 06:18

answered May 03 '15 at 11:01

ArtemGr

11,684
3
52
85

Sort of like JSDoc. I say it's more ergonomic too. You can see the full function documentation at a single glance. – Paul-Sebastian Manole Feb 09 '20 at 14:18
updated for the P.S. linking to the issue. – Bryan Larsen Sep 03 '22 at 12:42
Just want to points out other official reference: https://doc.rust-lang.org/beta/rust-by-example/meta/doc.html – Rahmat Nazali Salimi Jan 03 '23 at 01:44

score 26 · Accepted Answer · answered Aug 30 '21 at 11:04

According to the rust documentation, function docs are formatted like this:

#![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();
}

score 22 · Answer 3 · answered May 03 '15 at 22:47

22

Is there an "official" way to document them

There is not currently an official way to document arguments.

answered May 03 '15 at 22:47

Steve Klabnik

14,521
4
58
99

2

Since this answer is 3 years old, I'd like to inquire if there are any updates about this - at least I couldn't find any. – Philipp Ludwig Mar 22 '18 at 10:57
5

There is not. Most people rely on the type and argument name, and it tends to be pretty clear. If clarifications are needed, most use a bit of prose, rather than something that rustdoc needs to understand. – Steve Klabnik Mar 22 '18 at 11:00

How do you document function arguments?

3 Answers3