Allow doc attributes in ioctl macro

1 files changed, 54 insertions, 13 deletions

diff --git a/src/sys/ioctl/mod.rs b/src/sys/ioctl/mod.rs
index 4db3fe76..b29c8b42 100644
--- a/src/sys/ioctl/mod.rs
+++ b/src/sys/ioctl/mod.rs
@@ -197,6 +197,34 @@
 //! of lines defining macros which use `_IO`, `_IOR`, `_IOW`, `_IOC`, and `_IORW`. Some `ioctl`s are
 //! documented directly in the headers defining their constants, but others have more extensive
 //! documentation in man pages (like termios' `ioctl`s which are in `tty_ioctl(4)`).
+//!
+//! Documenting the generated functions
+//! ===================================
+//!
+//! In many cases, users will wish for the functions generated by the `ioctl`
+//! macro to be public and documented. For this reason, the generated functions
+//! are public by default. If you wish to hide the ioctl, you will need to put
+//! them in a private module.
+//!
+//! For documentation, it is possible to use doc comments inside the `ioctl!`
+//! macro. Here is an example :
+//!
+//! ```
+//! # #[macro_use] extern crate nix;
+//! # use nix::libc::c_int;
+//! ioctl! {
+//!     /// Make the given terminal the controlling terminal of the calling process. The calling
+//!     /// process must be a session leader and not have a controlling terminal already. If the
+//!     /// terminal is already the controlling terminal of a different session group then the
+//!     /// ioctl will fail with **EPERM**, unless the caller is root (more precisely: has the
+//!     /// **CAP_SYS_ADMIN** capability) and arg equals 1, in which case the terminal is stolen
+//!     /// and all processes that had it as controlling terminal lose it.
+//!     read tiocsctty with b't', 19; c_int
+//! }
+//!
+//! # fn main() {}
+//! ```
+//!
 #[cfg(any(target_os = "linux", target_os = "android"))]
 #[path = "platform/linux.rs"]
 #[macro_use]
@@ -228,89 +256,102 @@ macro_rules! convert_ioctl_res {
 /// Generates ioctl functions. See [::sys::ioctl](sys/ioctl/index.html).
 #[macro_export]
 macro_rules! ioctl {
-    (bad none $name:ident with $nr:expr) => (
+    ($(#[$attr:meta])* bad none $name:ident with $nr:expr) => (
+        $(#[$attr])*
         pub unsafe fn $name(fd: $crate::libc::c_int)
                             -> $crate::Result<$crate::libc::c_int> {
             convert_ioctl_res!($crate::libc::ioctl(fd, $nr as $crate::sys::ioctl::ioctl_num_type))
         }
         );
-    (bad read $name:ident with $nr:expr; $ty:ty) => (
+    ($(#[$attr:meta])* bad read $name:ident with $nr:expr; $ty:ty) => (
+        $(#[$attr])*
         pub unsafe fn $name(fd: $crate::libc::c_int,
                             data: *mut $ty)
                             -> $crate::Result<$crate::libc::c_int> {
             convert_ioctl_res!($crate::libc::ioctl(fd, $nr as $crate::sys::ioctl::ioctl_num_type, data))
         }
         );
-    (bad write_ptr $name:ident with $nr:expr; $ty:ty) => (
+    ($(#[$attr:meta])* bad write_ptr $name:ident with $nr:expr; $ty:ty) => (
+        $(#[$attr])*
         pub unsafe fn $name(fd: $crate::libc::c_int,
                             data: *const $ty)
                             -> $crate::Result<$crate::libc::c_int> {
             convert_ioctl_res!($crate::libc::ioctl(fd, $nr as $crate::sys::ioctl::ioctl_num_type, data))
         }
         );
-    (bad write_int $name:ident with $nr:expr) => (
+    ($(#[$attr:meta])* bad write_int $name:ident with $nr:expr) => (
+        $(#[$attr])*
         pub unsafe fn $name(fd: $crate::libc::c_int,
                             data: $crate::libc::c_int)
                             -> $crate::Result<$crate::libc::c_int> {
             convert_ioctl_res!($crate::libc::ioctl(fd, $nr as $crate::sys::ioctl::ioctl_num_type, data))
         }
         );
-    (bad readwrite $name:ident with $nr:expr; $ty:ty) => (
+    ($(#[$attr:meta])* bad readwrite $name:ident with $nr:expr; $ty:ty) => (
+        $(#[$attr])*
         pub unsafe fn $name(fd: $crate::libc::c_int,
                             data: *mut $ty)
                             -> $crate::Result<$crate::libc::c_int> {
             convert_ioctl_res!($crate::libc::ioctl(fd, $nr as $crate::sys::ioctl::ioctl_num_type, data))
         }
         );
-    (none $name:ident with $ioty:expr, $nr:expr) => (
+    ($(#[$attr:meta])* none $name:ident with $ioty:expr, $nr:expr) => (
+        $(#[$attr])*
         pub unsafe fn $name(fd: $crate::libc::c_int)
                             -> $crate::Result<$crate::libc::c_int> {
             convert_ioctl_res!($crate::libc::ioctl(fd, io!($ioty, $nr) as $crate::sys::ioctl::ioctl_num_type))
         }
         );
-    (read $name:ident with $ioty:expr, $nr:expr; $ty:ty) => (
+    ($(#[$attr:meta])* read $name:ident with $ioty:expr, $nr:expr; $ty:ty) => (
+        $(#[$attr])*
         pub unsafe fn $name(fd: $crate::libc::c_int,
                             data: *mut $ty)
                             -> $crate::Result<$crate::libc::c_int> {
             convert_ioctl_res!($crate::libc::ioctl(fd, ior!($ioty, $nr, ::std::mem::size_of::<$ty>()) as $crate::sys::ioctl::ioctl_num_type, data))
         }
         );
-    (write_ptr $name:ident with $ioty:expr, $nr:expr; $ty:ty) => (
+    ($(#[$attr:meta])* write_ptr $name:ident with $ioty:expr, $nr:expr; $ty:ty) => (
+        $(#[$attr])*
         pub unsafe fn $name(fd: $crate::libc::c_int,
                             data: *const $ty)
                             -> $crate::Result<$crate::libc::c_int> {
             convert_ioctl_res!($crate::libc::ioctl(fd, iow!($ioty, $nr, ::std::mem::size_of::<$ty>()) as $crate::sys::ioctl::ioctl_num_type, data))
         }
         );
-    (write_int $name:ident with $ioty:expr, $nr:expr) => (
+    ($(#[$attr:meta])* write_int $name:ident with $ioty:expr, $nr:expr) => (
+        $(#[$attr])*
         pub unsafe fn $name(fd: $crate::libc::c_int,
                             data: $crate::libc::c_int)
                             -> $crate::Result<$crate::libc::c_int> {
             convert_ioctl_res!($crate::libc::ioctl(fd, iow!($ioty, $nr, ::std::mem::size_of::<$crate::libc::c_int>()) as $crate::sys::ioctl::ioctl_num_type, data))
         }
         );
-    (readwrite $name:ident with $ioty:expr, $nr:expr; $ty:ty) => (
+    ($(#[$attr:meta])* readwrite $name:ident with $ioty:expr, $nr:expr; $ty:ty) => (
+        $(#[$attr])*
         pub unsafe fn $name(fd: $crate::libc::c_int,
                             data: *mut $ty)
                             -> $crate::Result<$crate::libc::c_int> {
             convert_ioctl_res!($crate::libc::ioctl(fd, iorw!($ioty, $nr, ::std::mem::size_of::<$ty>()) as $crate::sys::ioctl::ioctl_num_type, data))
         }
         );
-    (read_buf $name:ident with $ioty:expr, $nr:expr; $ty:ty) => (
+    ($(#[$attr:meta])* read_buf $name:ident with $ioty:expr, $nr:expr; $ty:ty) => (
+        $(#[$attr])*
         pub unsafe fn $name(fd: $crate::libc::c_int,
                             data: &mut [$ty])
                             -> $crate::Result<$crate::libc::c_int> {
             convert_ioctl_res!($crate::libc::ioctl(fd, ior!($ioty, $nr, data.len() * ::std::mem::size_of::<$ty>()) as $crate::sys::ioctl::ioctl_num_type, data))
         }
         );
-    (write_buf $name:ident with $ioty:expr, $nr:expr; $ty:ty) => (
+    ($(#[$attr:meta])* write_buf $name:ident with $ioty:expr, $nr:expr; $ty:ty) => (
+        $(#[$attr])*
         pub unsafe fn $name(fd: $crate::libc::c_int,
                             data: &[$ty])
                             -> $crate::Result<$crate::libc::c_int> {
             convert_ioctl_res!($crate::libc::ioctl(fd, iow!($ioty, $nr, data.len() * ::std::mem::size_of::<$ty>()) as $crate::sys::ioctl::ioctl_num_type, data))
         }
         );
-    (readwrite_buf $name:ident with $ioty:expr, $nr:expr; $ty:ty) => (
+    ($(#[$attr:meta])* readwrite_buf $name:ident with $ioty:expr, $nr:expr; $ty:ty) => (
+        $(#[$attr])*
         pub unsafe fn $name(fd: $crate::libc::c_int,
                             data: &mut [$ty])
                             -> $crate::Result<$crate::libc::c_int> {