Attribute Macro document_parameters

Source

#[document_parameters]

Expand description

Generates documentation for a function’s parameters.

This macro analyzes the function signature and generates a documentation comment list based on the provided descriptions. It also handles curried return types.

It can also be used on impl blocks to provide a common description for the receiver (self) parameter of methods within the block.

§Syntax

For functions:

#[document_parameters(
    "Description for first parameter",
    ("overridden_name", "Description for second parameter"),
    ...
)]
pub fn function_name(params) -> impl Fn(...) { ... }

For impl blocks:

#[document_parameters("Description for receiver")]
impl MyType {
    #[document_parameters]
    pub fn method_with_receiver(&self) { ... }

    #[document_parameters("Description for arg")]
    pub fn method_with_args(&self, arg: i32) { ... }
}

§Parameters

Descriptions: A comma-separated list. Each entry can be either a string literal or a tuple of two string literals (Name, Description).
For impl blocks: Exactly one string literal describing the receiver parameter.

§Generates

A list of documentation comments, one for each parameter, prepended to the function definition.

§Examples

// Invocation
#[document_parameters(
    "The first input value.",
    ("y", "The second input value.")
)]
pub fn foo(x: i32) -> impl Fn(i32) -> i32 { ... }

// Expanded code
/// * `x`: The first input value.
/// * `y`: The second input value.
pub fn foo(x: i32) -> impl Fn(i32) -> i32 { ... }

// Invocation on impl block
#[document_parameters("The list instance")]
impl<A> MyList<A> {
    #[document_parameters("The element to push")]
    pub fn push(&mut self, item: A) { ... }
}

// Expanded code
impl<A> MyList<A> {
    /// * `&mut self`: The list instance
    /// * `item`: The element to push
    pub fn push(&mut self, item: A) { ... }
}

§Constraints

The number of arguments must exactly match the number of function parameters (excluding self but including parameters from curried return types).

§Configuration

This macro can be configured via Cargo.toml under [package.metadata.document_signature].

apply_macro_aliases: A list of macro names that should be treated as Apply! for curried parameter extraction.

Example:

[package.metadata.document_signature]
apply_macro_aliases = ["MyApply"]

document_parameters