JoinReadWrite: Discuss using .reunite() or .unsplit()

As per
  https://gitlab.torproject.org/tpo/core/arti/-/merge_requests/1115#note_2894238

And move the "This is the converse" comment to somewhere it actually
appears in public docs.  The module-level docs only appear with
--document-private-items because the modules themselves are private.

crates/tor-async-utils/src/join_read_write.rs

@@ -1,7 +1,4 @@
 //! Join a readable and writeable into a single `AsyncRead` + `AsyncWrite`
-//!
-//! In some sense this is the converse of
-//! [`AsyncReadExt::split`](futures::AsyncReadExt::split).
 
 use std::io::Error;
 use std::pin::Pin;
@@ -16,6 +13,11 @@ use pin_project::pin_project;
 ///
 /// `AsyncWrite` is forwarded to `W`.
 ///
+/// This is the converse of
+/// [`AsyncReadExt::split`](futures::AsyncReadExt::split).
+/// But, if `R` and `W` came from splitting a single `AsyncRead + AsyncWrite`,
+/// you probably want the `reunite` or `unsplit` method, instead of `JoinReadWrite`.
+///
 /// Does *not* implement any kind of flushing behaviour when switching between reading and writing.
 #[pin_project]
 pub struct JoinReadWrite<R: AsyncRead, W: AsyncWrite> {