Use of ioctl!() in a crate with [warn(missing_docs)]

[agrover]

We'd like to enable [warn(missing_docs)] for our crate that uses nix, but when doing so we get this warning:

   Compiling devicemapper v0.4.3 (file:///home/agrover/git/stratis/devicemapper-rs)
warning: missing documentation for a function
  --> src/util.rs:11:1
   |
11 | ioctl!(read blkgetsize64 with 0x12, 114; u64);
   | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   |
note: lint level defined here
  --> src/lib.rs:43:9
   |
43 | #![warn(missing_docs)]
   |         ^^^^^^^^^^^^
   = note: this error originates in a macro outside of the current crate

    Finished dev [unoptimized + debuginfo] target(s) in 1.58 secs

I don't see a way in my nix-using crate to silence this (without disabling the warning, of course!) Thanks.

[kamalmarhubi]

@agrover thanks for the report. I'm not too familiar with the ioctl stuff, so I can't answer immediately. In the meantime, does putting #[allow(missing_docs)] on that declaration work?

[roblabla]

The ioctl! macro generates a pub function, so missing_docs will require you to document it. I haven't tried, but I'm pretty sure adding some docs above it would fix the issue, e.g. :

/// This is a binding to the blkgetsize64 ioctl
ioctl!(read blkgetsize64 with 0x12, 114; u64);

If blkgetsize64 shouldn't be publicly exported, then you should put it in a private module instead.

[roblabla]

After some investigation, it turns out it's impossible to document functions generated by a macro in rust. See https://stackoverflow.com/questions/41361897/documenting-a-function-created-with-a-macro-in-rust.

So I'm wondering if it'd be possible to transform ioctl! to support something like

ioctl! {
    /// Some doc-comments
    readwrite some_ioctl(type: b'b', nr: 1, arg: some_arg)
}

This syntax looks dreadful so if someone has a better idea, feel free to comment. But the basic idea is to allow the doc comments to be inside the macro invocation so we can use it to generate the function with it.