Clarify `Box<T>` representation and its use in FFI

This officializes what was only shown as a code example in [the unsafe code guidelines](https://rust-lang.github.io/unsafe-code-guidelines/layout/function-pointers.html?highlight=box#use) and follows [the discussion](https://github.com/rust-lang/unsafe-code-guidelines/issues/157) in the corresponding repository.

It is also related to [the issue](https://github.com/rust-lang/rust/issues/52976) regarding marking `Box<T>` `#[repr(transparent)]`.

1 files changed, 22 insertions, 0 deletions

diff --git a/src/liballoc/boxed.rs b/src/liballoc/boxed.rs
index 01dee0a3943..50174c3f279 100644
--- a/src/liballoc/boxed.rs
+++ b/src/liballoc/boxed.rs
@@ -63,6 +63,28 @@
 //! T` obtained from `Box::<T>::into_raw` may be deallocated using the
 //! [`Global`] allocator with `Layout::for_value(&*value)`.
 //!
+//! `Box<T>` has the same representation as `*mut T`. In particular, when
+//! `T: Sized`, this means that `Box<T>` has the same representation as
+//! a C pointer, making the following code valid in FFI:
+//!
+//! ```c
+//! /* C header */
+//! struct Foo* foo(); /* Returns ownership */
+//! void bar(struct Foo*); /* `bar` takes ownership */
+//! ```
+//!
+//! ```
+//! #[repr(C)]
+//! pub struct Foo;
+//!
+//! #[no_mangle]
+//! pub extern "C" fn foo() -> Box<Foo> {
+//!     Box::new(Foo)
+//! }
+//!
+//! #[no_mangle]
+//! pub extern "C" fn bar(_: Option<Box<Foo>>) {}
+//! ```
 //!
 //! [dereferencing]: ../../std/ops/trait.Deref.html
 //! [`Box`]: struct.Box.html