Document the nullable pointer optimization in the FFI guide

Closes #8748

1 files changed, 13 insertions, 0 deletions

diff --git a/src/doc/guide-ffi.md b/src/doc/guide-ffi.md
index 449c3ca6941..95c94ce0e5d 100644
--- a/src/doc/guide-ffi.md
+++ b/src/doc/guide-ffi.md
@@ -496,3 +496,16 @@ NUL-terminated string for interoperability with C, you should use the `c_str::to
 
 The standard library includes type aliases and function definitions for the C standard library in
 the `libc` module, and Rust links against `libc` and `libm` by default.
+
+# The "nullable pointer optimization"
+
+Certain types are defined to not be `null`. This includes references (`&T`,
+`&mut T`), owning pointers (`~T`), and function pointers (`extern "abi"
+fn()`). When interfacing with C, pointers that might be null are often used.
+As a special case, a generic `enum` that contains exactly two variants, one of
+which contains no data and the other containing a single field, is eligible
+for the "nullable pointer optimization". When such an enum is instantiated
+with one of the non-nullable types, it is represented as a single pointer,
+and the non-data variant is represented as the null pointer. So
+`Option<extern "C" fn(c_int) -> c_int>` is how one represents a nullable
+function pointer using the C ABI.