1 files changed, 42 insertions, 0 deletions
diff --git a/src/libstd/keyword_docs.rs b/src/libstd/keyword_docs.rs
index 5026ca4d722..a09917afbad 100644
--- a/src/libstd/keyword_docs.rs
+++ b/src/libstd/keyword_docs.rs
@@ -179,6 +179,48 @@ mod crate_keyword { }
 /// [Reference]: https://doc.rust-lang.org/reference/items/enumerations.html
 mod enum_keyword { }
 
+#[doc(keyword = "extern")]
+//
+/// For external connections in Rust code.
+///
+/// The `extern` keyword is used in two places in Rust. One is in conjunction with the [`crate`]
+/// keyword to make your Rust code aware of other Rust crates in your project, i.e. `extern crate
+/// lazy_static;`. The other use is in foreign function interfaces (FFI).
+///
+/// `extern` is used in two different contexts within FFI. The first is in the form of external
+/// blcoks, for declaring function interfaces that Rust code can call foreign code by.
+///
+/// ```rust ignore
+/// #[link(name = "my_c_library")]
+/// extern "C" {
+///     fn my_c_function(x: i32) -> bool;
+/// }
+/// ```
+///
+/// This code would attempt to link with libmy_c_library.so on unix-like systems and
+/// my_c_library.dll on Windows at runtime, and panic if it can't find something to link to. Rust
+/// code could then use `my_c_function` as if it were any other unsafe Rust function. Working with
+/// non-Rust languages and FFI is inherently unsafe, so wrappers are usually built around C APIs.
+///
+/// The mirror use case of FFI is also done via the `extern` keyword:
+///
+/// ```rust
+/// # #![allow(private_no_mangle_fns)]
+/// #[no_mangle]
+/// pub extern fn callable_from_c(x: i32) -> bool {
+///     x % 3 == 0
+/// }
+/// ```
+///
+/// If compiled as a dylib, the resulting .so could then be linked to from a C library, and the
+/// function could be used as if it was from any other library.
+///
+/// For more information on FFI, check the [Rust book] or the [Reference].
+///
+/// [Rust book]: https://doc.rust-lang.org/book/second-edition/ch19-01-unsafe-rust.html#using-extern-functions-to-call-external-code
+/// [Reference]: https://doc.rust-lang.org/reference/items/external-blocks.html
+mod extern_keyword { }
+
 #[doc(keyword = "fn")]
 //
 /// The `fn` keyword.