From 9d4be0b243b6a0d61c7fa1b33d6b1f978f1b6601 Mon Sep 17 00:00:00 2001 From: Justus Winter Date: Mon, 4 Jul 2022 13:36:42 +0200 Subject: buffered-reader, openpgp: Fix macro's doctests. - Previously, the doctests for the macros were not run, and hence not tested. Fix the few issues that came up when Rust 1.62 started running doctests. - We cannot test the macros in doctests, because the macros are not public. Add equivalent unit tests instead. - Fixes #893. --- buffered-reader/src/macros.rs | 58 ++++++++++++++++++++++++------ openpgp/src/macros.rs | 83 ++++++++++++++++++++++++++++++++++++------- 2 files changed, 118 insertions(+), 23 deletions(-) diff --git a/buffered-reader/src/macros.rs b/buffered-reader/src/macros.rs index 2738d178..eafb6add 100644 --- a/buffered-reader/src/macros.rs +++ b/buffered-reader/src/macros.rs @@ -57,25 +57,25 @@ macro_rules! tracer { /// /// For most types just call it after defining the type: /// -/// ``` +/// ```ignore /// pub struct MyStruct {} /// assert_send_and_sync!(MyStruct); /// ``` /// /// For types with lifetimes, use the anonymous lifetime: /// -/// ``` -/// pub struct WithLifetime<'a> {} -/// assert_send_and_sync!(MyStruct<'_>); +/// ```ignore +/// pub struct WithLifetime<'a> { _p: std::marker::PhantomData<&'a ()> } +/// assert_send_and_sync!(WithLifetime<'_>); /// ``` /// /// For a type generic over another type `W`, /// pass the type `W` as a where clause /// including a trait bound when needed: /// -/// ``` -/// pub struct MyWriter {} -/// assert_send_and_sync!(MyWriterStruct where W: io::Write); +/// ```ignore +/// pub struct MyWriter { _p: std::marker::PhantomData } +/// assert_send_and_sync!(MyWriter where W: std::io::Write); /// ``` /// /// This will assert that `MyWriterStruct` is `Send` and `Sync` @@ -85,16 +85,22 @@ macro_rules! tracer { /// Just make sure to list all the types - even those without additional /// trait bounds: /// -/// ``` -/// pub struct MyWriterWithLifetime<'a, C, W: io::Write> {} -/// assert_send_and_sync!(MyWriterStruct<'_, C, W> where C, W: io::Write); +/// ```ignore +/// pub struct MyWriterWithLifetime<'a, C, W: std::io::Write> { +/// _p: std::marker::PhantomData<&'a (C, W)>, +/// } +/// assert_send_and_sync!(MyWriterWithLifetime<'_, C, W> where C, W: std::io::Write); /// ``` /// /// If you need multiple additional trait bounds on a single type /// you can add them separated by `+` like in normal where clauses. /// However you have to make sure they are `Identifiers` like `Write`. -/// In macro patterns `Paths` (like `io::Write`) may not be followed +/// In macro patterns `Paths` (like `std::io::Write`) may not be followed /// by `+` characters. +// Note: We cannot test the macro in doctests, because the macro is +// not public. We test the cases in the test module below, instead. +// If you change the examples here, propagate the changes to the +// module below. macro_rules! assert_send_and_sync { ( $x:ty where $( $g:ident$( : $a:path )? $(,)?)*) => { impl<$( $g ),*> crate::macros::Sendable for $x @@ -120,3 +126,33 @@ macro_rules! assert_send_and_sync { pub(crate) trait Sendable : Send {} pub(crate) trait Syncable : Sync {} + +/// We cannot test the macro in doctests, because the macro is not +/// public. We test the cases here, instead. If you change the +/// examples here, propagate the changes to the docstring above. +#[cfg(test)] +mod test { + /// For most types just call it after defining the type: + pub struct MyStruct {} + assert_send_and_sync!(MyStruct); + + /// For types with lifetimes, use the anonymous lifetime: + pub struct WithLifetime<'a> { _p: std::marker::PhantomData<&'a ()> } + assert_send_and_sync!(WithLifetime<'_>); + + /// For a type generic over another type `W`, pass the type `W` as + /// a where clause including a trait bound when needed: + pub struct MyWriter { _p: std::marker::PhantomData } + assert_send_and_sync!(MyWriter where W: std::io::Write); + + /// This will assert that `MyWriterStruct` is `Send` and `Sync` + /// if `W` is `Send` and `Sync`. + /// + /// You can also combine the two and be generic over multiple + /// types. Just make sure to list all the types - even those + /// without additional trait bounds: + pub struct MyWriterWithLifetime<'a, C, W: std::io::Write> { + _p: std::marker::PhantomData<&'a (C, W)>, + } + assert_send_and_sync!(MyWriterWithLifetime<'_, C, W> where C, W: std::io::Write); +} diff --git a/openpgp/src/macros.rs b/openpgp/src/macros.rs index e7544083..11f334d0 100644 --- a/openpgp/src/macros.rs +++ b/openpgp/src/macros.rs @@ -67,13 +67,17 @@ macro_rules! tracer { /// displays the output on stderr. The output is prefixed with label, /// if it is provided. /// -/// ``` +/// ```ignore /// let result = time_it!("Some code", 10, { /// // Some code. /// 5 /// }); /// assert_eq!(result, 5); /// ``` +// Note: We cannot test the macro in doctests, because the macro is +// not public. We test the cases in the test module below, instead. +// If you change the examples here, propagate the changes to the +// module below. #[allow(unused_macros)] macro_rules! time_it { ( $label:expr, $ms_threshold:expr, $body:expr ) => {{ @@ -109,29 +113,48 @@ macro_rules! time_it { }; } +/// We cannot test the macro in doctests, because the macro is not +/// public. We test the cases here, instead. If you change the +/// examples here, propagate the changes to the docstring above. +#[cfg(test)] +mod test_time_it { + /// This macro measures the wall time it takes to execute the + /// block. If the time is at least $ms_threshold (in + /// milli-seconds), then it displays the output on stderr. The + /// output is prefixed with label, if it is provided. + #[test] + fn time_it() { + let result = time_it!("Some code", 10, { + // Some code. + 5 + }); + assert_eq!(result, 5); + } +} + /// A simple shortcut for ensuring a type is send and sync. /// /// For most types just call it after defining the type: /// -/// ``` +/// ```ignore /// pub struct MyStruct {} /// assert_send_and_sync!(MyStruct); /// ``` /// /// For types with lifetimes, use the anonymous lifetime: /// -/// ``` -/// pub struct WithLifetime<'a> {} -/// assert_send_and_sync!(MyStruct<'_>); +/// ```ignore +/// pub struct WithLifetime<'a> { _p: std::marker::PhantomData<&'a ()> } +/// assert_send_and_sync!(WithLifetime<'_>); /// ``` /// /// For a type generic over another type `W`, /// pass the type `W` as a where clause /// including a trait bound when needed: /// -/// ``` -/// pub struct MyWriter {} -/// assert_send_and_sync!(MyWriterStruct where W: io::Write); +/// ```ignore +/// pub struct MyWriter { _p: std::marker::PhantomData } +/// assert_send_and_sync!(MyWriter where W: std::io::Write); /// ``` /// /// This will assert that `MyWriterStruct` is `Send` and `Sync` @@ -141,16 +164,22 @@ macro_rules! time_it { /// Just make sure to list all the types - even those without additional /// trait bounds: /// -/// ``` -/// pub struct MyWriterWithLifetime<'a, C, W: io::Write> {}; -/// assert_send_and_sync!(MyWriterStruct<'_, C, W> where C, W: io::Write); +/// ```ignore +/// pub struct MyWriterWithLifetime<'a, C, W: std::io::Write> { +/// _p: std::marker::PhantomData<&'a (C, W)>, +/// } +/// assert_send_and_sync!(MyWriterWithLifetime<'_, C, W> where C, W: std::io::Write); /// ``` /// /// If you need multiple additional trait bounds on a single type /// you can add them separated by `+` like in normal where clauses. /// However you have to make sure they are `Identifiers` like `Write`. -/// In macro patterns `Paths` (like `io::Write`) may not be followed +/// In macro patterns `Paths` (like `std::io::Write`) may not be followed /// by `+` characters. +// Note: We cannot test the macro in doctests, because the macro is +// not public. We test the cases in the test module below, instead. +// If you change the examples here, propagate the changes to the +// module below. macro_rules! assert_send_and_sync { ( $x:ty where $( $g:ident$( : $a:path )? $(,)?)*) => { impl<$( $g ),*> crate::types::Sendable for $x @@ -173,3 +202,33 @@ macro_rules! assert_send_and_sync { impl crate::types::Syncable for $x {} }; } + +/// We cannot test the macro in doctests, because the macro is not +/// public. We test the cases here, instead. If you change the +/// examples here, propagate the changes to the docstring above. +#[cfg(test)] +mod test_assert_send_and_sync { + /// For most types just call it after defining the type: + pub struct MyStruct {} + assert_send_and_sync!(MyStruct); + + /// For types with lifetimes, use the anonymous lifetime: + pub struct WithLifetime<'a> { _p: std::marker::PhantomData<&'a ()> } + assert_send_and_sync!(WithLifetime<'_>); + + /// For a type generic over another type `W`, pass the type `W` as + /// a where clause including a trait bound when needed: + pub struct MyWriter { _p: std::marker::PhantomData } + assert_send_and_sync!(MyWriter where W: std::io::Write); + + /// This will assert that `MyWriterStruct` is `Send` and `Sync` + /// if `W` is `Send` and `Sync`. + /// + /// You can also combine the two and be generic over multiple + /// types. Just make sure to list all the types - even those + /// without additional trait bounds: + pub struct MyWriterWithLifetime<'a, C, W: std::io::Write> { + _p: std::marker::PhantomData<&'a (C, W)>, + } + assert_send_and_sync!(MyWriterWithLifetime<'_, C, W> where C, W: std::io::Write); +} -- cgit v1.2.3