1
Fork 0

Add docs on extern keyword

This commit is contained in:
iirelu 2018-09-09 13:23:34 +02:00
parent f15a1ec45d
commit f91ad440ef

View file

@ -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.