diff options
author | Justus Winter <justus@sequoia-pgp.org> | 2022-07-04 13:36:42 +0200 |
---|---|---|
committer | Justus Winter <justus@sequoia-pgp.org> | 2022-07-04 13:36:42 +0200 |
commit | 9d4be0b243b6a0d61c7fa1b33d6b1f978f1b6601 (patch) | |
tree | 12e583969d3ea1caea18b9900052f29a4447964c | |
parent | 53d84e2949f7307189867d5e11d6d6762f945f88 (diff) |
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.
-rw-r--r-- | buffered-reader/src/macros.rs | 58 | ||||
-rw-r--r-- | 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<W: io::Write> {} -/// assert_send_and_sync!(MyWriterStruct<W> where W: io::Write); +/// ```ignore +/// pub struct MyWriter<W: std::io::Write> { _p: std::marker::PhantomData<W> } +/// assert_send_and_sync!(MyWriter<W> where W: std::io::Write); /// ``` /// /// This will assert that `MyWriterStruct<W>` 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<W: std::io::Write> { _p: std::marker::PhantomData<W> } + assert_send_and_sync!(MyWriter<W> where W: std::io::Write); + + /// This will assert that `MyWriterStruct<W>` 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<W: io::Write> {} -/// assert_send_and_sync!(MyWriterStruct<W> where W: io::Write); +/// ```ignore +/// pub struct MyWriter<W: std::io::Write> { _p: std::marker::PhantomData<W> } +/// assert_send_and_sync!(MyWriter<W> where W: std::io::Write); /// ``` /// /// This will assert that `MyWriterStruct<W>` 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<W: std::io::Write> { _p: std::marker::PhantomData<W> } + assert_send_and_sync!(MyWriter<W> where W: std::io::Write); + + /// This will assert that `MyWriterStruct<W>` 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); +} |