From b874e3200668d2973d29066bd2f5ef186f383c4b Mon Sep 17 00:00:00 2001
From: Taiki Endo <te316e89@gmail.com>
Date: Wed, 30 Nov 2022 13:49:57 +0900
Subject: [PATCH 1/2] Move doc(hidden) items to __private module

To clarify that they are not public APIs.
---
 async-stream-impl/src/lib.rs | 10 +++++-----
 async-stream/src/lib.rs      | 23 ++++++++++-------------
 async-stream/src/yielder.rs  |  1 +
 3 files changed, 16 insertions(+), 18 deletions(-)

diff --git a/async-stream-impl/src/lib.rs b/async-stream-impl/src/lib.rs
index db4e0fd..bae7813 100644
--- a/async-stream-impl/src/lib.rs
+++ b/async-stream-impl/src/lib.rs
@@ -173,7 +173,7 @@ impl VisitMut for Scrub<'_> {
                     };
                     #label
                     loop {
-                        let #pat = match #crate_path::reexport::next(&mut __pinned).await {
+                        let #pat = match #crate_path::__private::next(&mut __pinned).await {
                             ::core::option::Option::Some(e) => e,
                             ::core::option::Option::None => break,
                         };
@@ -227,8 +227,8 @@ pub fn stream_inner(input: TokenStream) -> TokenStream {
     };
 
     quote!({
-        let (mut __yield_tx, __yield_rx) = #crate_path::yielder::pair();
-        #crate_path::AsyncStream::new(__yield_rx, async move {
+        let (mut __yield_tx, __yield_rx) = #crate_path::__private::yielder::pair();
+        #crate_path::__private::AsyncStream::new(__yield_rx, async move {
             #dummy_yield
             #(#stmts)*
         })
@@ -261,8 +261,8 @@ pub fn try_stream_inner(input: TokenStream) -> TokenStream {
     };
 
     quote!({
-        let (mut __yield_tx, __yield_rx) = #crate_path::yielder::pair();
-        #crate_path::AsyncStream::new(__yield_rx, async move {
+        let (mut __yield_tx, __yield_rx) = #crate_path::__private::yielder::pair();
+        #crate_path::__private::AsyncStream::new(__yield_rx, async move {
             #dummy_yield
             #(#stmts)*
         })
diff --git a/async-stream/src/lib.rs b/async-stream/src/lib.rs
index bab0954..cb53d16 100644
--- a/async-stream/src/lib.rs
+++ b/async-stream/src/lib.rs
@@ -158,15 +158,7 @@
 
 mod async_stream;
 mod next;
-#[doc(hidden)]
-pub mod yielder;
-
-// Used by the macro, but not intended to be accessed publicly.
-#[doc(hidden)]
-pub use crate::async_stream::AsyncStream;
-
-#[doc(hidden)]
-pub use async_stream_impl;
+mod yielder;
 
 /// Asynchronous stream
 ///
@@ -198,7 +190,7 @@ pub use async_stream_impl;
 #[macro_export]
 macro_rules! stream {
     ($($tt:tt)*) => {
-        $crate::async_stream_impl::stream_inner!(($crate) $($tt)*)
+        $crate::__private::stream_inner!(($crate) $($tt)*)
     }
 }
 
@@ -234,12 +226,17 @@ macro_rules! stream {
 #[macro_export]
 macro_rules! try_stream {
     ($($tt:tt)*) => {
-        $crate::async_stream_impl::try_stream_inner!(($crate) $($tt)*)
+        $crate::__private::try_stream_inner!(($crate) $($tt)*)
     }
 }
 
+// Not public API.
 #[doc(hidden)]
-pub mod reexport {
-    #[doc(hidden)]
+pub mod __private {
+    pub use crate::async_stream::AsyncStream;
     pub use crate::next::next;
+    pub use async_stream_impl::{stream_inner, try_stream_inner};
+    pub mod yielder {
+        pub use crate::yielder::pair;
+    }
 }
diff --git a/async-stream/src/yielder.rs b/async-stream/src/yielder.rs
index 2482260..ba90e31 100644
--- a/async-stream/src/yielder.rs
+++ b/async-stream/src/yielder.rs
@@ -20,6 +20,7 @@ pub(crate) struct Enter<'a, T> {
     prev: *mut (),
 }
 
+#[doc(hidden)]
 pub fn pair<T>() -> (Sender<T>, Receiver<T>) {
     let tx = Sender { _p: PhantomData };
     let rx = Receiver { _p: PhantomData };

From 530fc8289c1abe1de6178c62020f101dee002fd1 Mon Sep 17 00:00:00 2001
From: Taiki Endo <te316e89@gmail.com>
Date: Wed, 30 Nov 2022 14:46:16 +0900
Subject: [PATCH 2/2] Make yielder::pair unsafe

---
 async-stream-impl/src/lib.rs | 4 ++--
 async-stream/src/yielder.rs  | 6 +++++-
 2 files changed, 7 insertions(+), 3 deletions(-)

diff --git a/async-stream-impl/src/lib.rs b/async-stream-impl/src/lib.rs
index bae7813..082f734 100644
--- a/async-stream-impl/src/lib.rs
+++ b/async-stream-impl/src/lib.rs
@@ -227,7 +227,7 @@ pub fn stream_inner(input: TokenStream) -> TokenStream {
     };
 
     quote!({
-        let (mut __yield_tx, __yield_rx) = #crate_path::__private::yielder::pair();
+        let (mut __yield_tx, __yield_rx) = unsafe { #crate_path::__private::yielder::pair() };
         #crate_path::__private::AsyncStream::new(__yield_rx, async move {
             #dummy_yield
             #(#stmts)*
@@ -261,7 +261,7 @@ pub fn try_stream_inner(input: TokenStream) -> TokenStream {
     };
 
     quote!({
-        let (mut __yield_tx, __yield_rx) = #crate_path::__private::yielder::pair();
+        let (mut __yield_tx, __yield_rx) = unsafe { #crate_path::__private::yielder::pair() };
         #crate_path::__private::AsyncStream::new(__yield_rx, async move {
             #dummy_yield
             #(#stmts)*
diff --git a/async-stream/src/yielder.rs b/async-stream/src/yielder.rs
index ba90e31..597e1c9 100644
--- a/async-stream/src/yielder.rs
+++ b/async-stream/src/yielder.rs
@@ -20,8 +20,12 @@ pub(crate) struct Enter<'a, T> {
     prev: *mut (),
 }
 
+// Note: It is considered unsound for anyone other than our macros to call
+// this function. This is a private API intended only for calls from our
+// macros, and users should never call it, but some people tend to
+// misinterpret it as fine to call unless it is marked unsafe.
 #[doc(hidden)]
-pub fn pair<T>() -> (Sender<T>, Receiver<T>) {
+pub unsafe fn pair<T>() -> (Sender<T>, Receiver<T>) {
     let tx = Sender { _p: PhantomData };
     let rx = Receiver { _p: PhantomData };
     (tx, rx)