Correctly use doc comments in macros

Our custom macros for conveniently creating types with additional meta
information for working with structopt do not actually use the doc
comments we have in place -- these comments are solely for in-source
documentation. We are an application and as such crates.io will not
automatically generate documentation.
All of that does not deter rustc from complaining that doc comments are
unused. In the past we tried to fudge that by adding a special
allowance, #[allow(unused_doc_comments)], but that seems to have seized
to work.
With this change we finally give in and move the doc comment into the
macro itself, where it will be used to annotate the generated type. This
step should hopefully silence rustc once and for all -- at the expense
of a slight decrease in readability.

3 files changed, 54 insertions, 44 deletions

diff --git a/src/arg_util.rs b/src/arg_util.rs
index 439a594..3a4c001 100644
--- a/src/arg_util.rs
+++ b/src/arg_util.rs
@@ -33,7 +33,10 @@ macro_rules! tr {
 }
 
 macro_rules! Command {
-  ( $name:ident, [ $( $(#[$doc:meta])* $var:ident$(($inner:ty))? => $exec:expr, ) *] ) => {
+  ( $(#[$docs:meta])* $name:ident, [
+    $( $(#[$doc:meta])* $var:ident$(($inner:ty))? => $exec:expr, ) *
+  ] ) => {
+    $(#[$docs])*
     #[derive(Debug, PartialEq, structopt::StructOpt)]
     pub enum $name {
       $(
@@ -63,7 +66,8 @@ macro_rules! Command {
 // TODO: Right now we hard code the derives we create. We may want to
 //       make this set configurable.
 macro_rules! Enum {
-  ( $name:ident, [ $( $var:ident => $str:expr, ) *] ) => {
+  ( $(#[$docs:meta])* $name:ident, [ $( $var:ident => $str:expr, ) *] ) => {
+    $(#[$docs])*
     #[derive(Clone, Copy, Debug, PartialEq)]
     pub enum $name {
       $(
diff --git a/src/args.rs b/src/args.rs
index 20392a8..91b340c 100644
--- a/src/args.rs
+++ b/src/args.rs
@@ -31,12 +31,13 @@ pub struct Args {
   pub cmd: Command,
 }
 
-/// The available Nitrokey models.
-#[allow(unused_doc_comments)]
-Enum! {DeviceModel, [
-  Pro => "pro",
-  Storage => "storage",
-]}
+Enum! {
+  /// The available Nitrokey models.
+  DeviceModel, [
+    Pro => "pro",
+    Storage => "storage",
+  ]
+}
 
 impl DeviceModel {
   pub fn as_user_facing_str(&self) -> &str {
@@ -56,32 +57,33 @@ impl From<DeviceModel> for nitrokey::Model {
   }
 }
 
-/// A top-level command for nitrocli.
-#[allow(unused_doc_comments)]
-Command! {Command, [
-  /// Reads or writes the device configuration
-  Config(ConfigArgs) => |ctx, args: ConfigArgs| args.subcmd.execute(ctx),
-  /// Interacts with the device's encrypted volume
-  Encrypted(EncryptedArgs) => |ctx, args: EncryptedArgs| args.subcmd.execute(ctx),
-  /// Interacts with the device's hidden volume
-  Hidden(HiddenArgs) => |ctx, args: HiddenArgs| args.subcmd.execute(ctx),
-  /// Lists the attached Nitrokey devices
-  List(ListArgs) => |ctx, args: ListArgs| crate::commands::list(ctx, args.no_connect),
-  /// Locks the connected Nitrokey device
-  Lock => crate::commands::lock,
-  /// Accesses one-time passwords
-  Otp(OtpArgs) => |ctx, args: OtpArgs| args.subcmd.execute(ctx),
-  /// Manages the Nitrokey PINs
-  Pin(PinArgs) => |ctx, args: PinArgs| args.subcmd.execute(ctx),
-  /// Accesses the password safe
-  Pws(PwsArgs) => |ctx, args: PwsArgs| args.subcmd.execute(ctx),
-  /// Performs a factory reset
-  Reset => crate::commands::reset,
-  /// Prints the status of the connected Nitrokey device
-  Status => crate::commands::status,
-  /// Interacts with the device's unencrypted volume
-  Unencrypted(UnencryptedArgs) => |ctx, args: UnencryptedArgs| args.subcmd.execute(ctx),
-]}
+Command! {
+  /// A top-level command for nitrocli.
+  Command, [
+    /// Reads or writes the device configuration
+    Config(ConfigArgs) => |ctx, args: ConfigArgs| args.subcmd.execute(ctx),
+    /// Interacts with the device's encrypted volume
+    Encrypted(EncryptedArgs) => |ctx, args: EncryptedArgs| args.subcmd.execute(ctx),
+    /// Interacts with the device's hidden volume
+    Hidden(HiddenArgs) => |ctx, args: HiddenArgs| args.subcmd.execute(ctx),
+    /// Lists the attached Nitrokey devices
+    List(ListArgs) => |ctx, args: ListArgs| crate::commands::list(ctx, args.no_connect),
+    /// Locks the connected Nitrokey device
+    Lock => crate::commands::lock,
+    /// Accesses one-time passwords
+    Otp(OtpArgs) => |ctx, args: OtpArgs| args.subcmd.execute(ctx),
+    /// Manages the Nitrokey PINs
+    Pin(PinArgs) => |ctx, args: PinArgs| args.subcmd.execute(ctx),
+    /// Accesses the password safe
+    Pws(PwsArgs) => |ctx, args: PwsArgs| args.subcmd.execute(ctx),
+    /// Performs a factory reset
+    Reset => crate::commands::reset,
+    /// Prints the status of the connected Nitrokey device
+    Status => crate::commands::status,
+    /// Interacts with the device's unencrypted volume
+    Unencrypted(UnencryptedArgs) => |ctx, args: UnencryptedArgs| args.subcmd.execute(ctx),
+  ]
+}
 
 #[derive(Debug, PartialEq, structopt::StructOpt)]
 pub struct ConfigArgs {
@@ -326,15 +328,16 @@ Command! {PinCommand, [
   Unblock => crate::commands::pin_unblock,
 ]}
 
-/// PIN type requested from pinentry.
-///
-/// The available PIN types correspond to the PIN types used by the Nitrokey devices:  user and
-/// admin.
-#[allow(unused_doc_comments)]
-Enum! {PinType, [
-  Admin => "admin",
-  User => "user",
-]}
+Enum! {
+  /// PIN type requested from pinentry.
+  ///
+  /// The available PIN types correspond to the PIN types used by the
+  /// Nitrokey devices: user and admin.
+  PinType, [
+    Admin => "admin",
+    User => "user",
+  ]
+}
 
 #[derive(Debug, PartialEq, structopt::StructOpt)]
 pub struct PinSetArgs {
diff --git a/var/shell-complete.rs b/var/shell-complete.rs
index 4793ed3..a6f476d 100644
--- a/var/shell-complete.rs
+++ b/var/shell-complete.rs
@@ -28,7 +28,10 @@ mod nitrocli {
 
   // We only need a stripped down version of the `Command` macro.
   macro_rules! Command {
-    ( $name:ident, [ $( $(#[$doc:meta])* $var:ident$(($inner:ty))? => $exec:expr, ) *] ) => {
+    ( $(#[$docs:meta])* $name:ident, [
+      $( $(#[$doc:meta])* $var:ident$(($inner:ty))? => $exec:expr, ) *
+    ] ) => {
+      $(#[$docs])*
       #[derive(Debug, PartialEq, structopt::StructOpt)]
       pub enum $name {
         $(