From 6dd0dafdd53b990cfba79529a36352e11fe0385e Mon Sep 17 00:00:00 2001 From: Daniel Mueller Date: Fri, 3 Jul 2020 08:30:57 -0700 Subject: 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. --- src/arg_util.rs | 8 +++-- src/args.rs | 85 ++++++++++++++++++++++++++------------------------- var/shell-complete.rs | 5 ++- 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 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 { $( -- cgit v1.2.1