ipc, net: Fix assert_send_and_sync'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.

  - Changes copied from 9d4be0b243b6a0d61c7fa1b33d6b1f978f1b6601.

  - Fixes #916.

2 files changed, 100 insertions, 27 deletions

diff --git a/ipc/src/macros.rs b/ipc/src/macros.rs
index cbfb7a44..3f99f2e6 100644
--- a/ipc/src/macros.rs
+++ b/ipc/src/macros.rs
@@ -85,7 +85,7 @@ macro_rules! platform {
 /// 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
@@ -131,25 +131,25 @@ macro_rules! time_it {
 ///
 /// 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`
@@ -159,30 +159,36 @@ 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
+        impl<$( $g ),*> crate::macros::Sendable for $x
             where $( $g: Send + Sync $( + $a )? ),*
             {}
-        impl<$( $g ),*> crate::types::Syncable for $x
+        impl<$( $g ),*> crate::macros::Syncable for $x
             where $( $g: Send + Sync $( + $a )? ),*
             {}
     };
     ( $x:ty where $( $g:ident$( : $a:ident $( + $b:ident )* )? $(,)?)*) => {
-        impl<$( $g ),*> crate::types::Sendable for $x
+        impl<$( $g ),*> crate::macros::Sendable for $x
             where $( $g: Send + Sync $( + $a $( + $b )* )? ),*
             {}
-        impl<$( $g ),*> crate::types::Syncable for $x
+        impl<$( $g ),*> crate::macros::Syncable for $x
             where $( $g: Send + Sync $( + $a $( + $b )* )? ),*
             {}
     };
@@ -191,5 +197,36 @@ macro_rules! assert_send_and_sync {
         impl crate::macros::Syncable for $x {}
     };
 }
+
 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/net/src/macros.rs b/net/src/macros.rs
index caad17f5..26b79408 100644
--- a/net/src/macros.rs
+++ b/net/src/macros.rs
@@ -4,25 +4,25 @@
 ///
 /// 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`
@@ -32,16 +32,22 @@
 /// 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
@@ -67,3 +73,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);
+}