Move doc(hidden) items to __private module and make yielder::pair unsafe

[taiki-e]

To clarify that they are not public APIs. (To prevent someone from accidentally using it...)

[trevyn]

If it’s known that these methods can cause UB if used incorrectly, and are actually pub, would it be appropriate to call the module __private_unsafe?

Otherwise, people might just consider it a potential semver-breaking module, not an actual safety issue.

[taiki-e]

would it be appropriate to call the module __private_unsafe

Disagreed. First of all, users should not use private APIs. I think the distinction between "safe" and "unsafe" private modules is misleading. (Even if it is a "safe" private module, it is not "fine" for users to use it.)

a potential semver-breaking module, not an actual safety issue.

Disagreed. Such APIs are usually called unstable instead of private.

That said, I don't think those who would abuse the private API care about documentation or convention...

[taiki-e]

That said, I don't think those who would abuse the private API care about documentation or convention...

Given this point, I think it would be difficult to completely deal with users who want to abuse the private API unless the yielder::pair is marked as unsafe -- added a commit to make yielder::pair unsafe.

async-stream/async-stream/src/yielder.rs

Lines 23 to 28 in 530fc82

	// 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 unsafe fn pair<T>() -> (Sender<T>, Receiver<T>) {

[trevyn]

added a commit to make yielder::pair unsafe.

Since this is adding an unsafe call inside of quote!, would this cause an issue if the user applies #![forbid(unsafe_code)]?

[taiki-e]

Since this is adding an unsafe call inside of quote!, would this cause an issue if the user applies #![forbid(unsafe_code)]?

No, unsafe_code will not trigger on unsafe keyword generated by external macros (except when the unsafe token has a span other than the call-site). (rust-lang/rust#52467)