Documenting a function created with a macro in Rust

Question

I tried to do

#![deny(missing_docs)]

in the rust. And I found that comments are ///simply ignored when a function is created using a macro like this:

/// docs
py_module_initializer!(libx, initlibx PyInit_libx |py, m| {
    Ok(())
});

with:

error: missing documentation for a function
113 | py_module_initializer!(libx initlibx PyInit_libx |py, m| {
    | ^

I thought the macro would just add a function definition after ///. What is wrong here?

Answer 1

Your comment on the doctor refers to invoking a macro that is useless in your case. To document the generated functions, you must write a comment on the document in the macro definition or modify your macro to also accept comments on the document. Let's take a look at this:

#![deny(missing_docs)]
//! crate docs

macro_rules! gen_fn {
    ($name:ident) => {
        /// generic doc comment... not very useful
        pub fn $name() {}
    }
}

gen_fn!(a);
gen_fn!(b);

, , doc . , :

macro_rules! gen_fn {
    ($(#[$attr:meta])* => $name:ident) => {
        $(#[$attr])*
        pub fn $name() {}
    }
}

gen_fn!{
    /// Doc comment for a
    => a
}

, doc #[doc(...)]. .