//
/// Import or rename items from other crates or modules.
///
-/// The documentation for this keyword is [not yet complete]. Pull requests welcome!
+/// Usually a `use` keyword is used to shorten the path required to refer to a module item.
+/// The keyword may appear in modules, blocks and even functions, usually at the top.
+///
+/// The most basic usage of the keyword is `use path::to::item;`,
+/// though a number of convenient shortcuts are supported:
+///
+/// * Simultaneously binding a list of paths with a common prefix,
+/// using the glob-like brace syntax use `a::b::{c, d, e::f, g::h::i};`
+/// * Simultaneously binding a list of paths with a common prefix and their common parent module,
+/// using the [`self`] keyword, such as `use a::b::{self, c, d::e};`
+/// * Rebinding the target name as a new local name, using the syntax `use p::q::r as x;`.
+/// This can also be used with the last two features: `use a::b::{self as ab, c as abc}`.
+/// * Binding all paths matching a given prefix,
+/// using the asterisk wildcard syntax `use a::b::*;`.
+/// * Nesting groups of the previous features multiple times,
+/// such as `use a::b::{self as ab, c, d::{*, e::f}};`
+/// * Reexporting with visibility modifiers such as `pub use a::b;`
+/// * Importing with `_` to only import the methods of the item without binding it to a name
+/// (to avoid conflict for example): `use ::std::io::Read as _;`.
+///
+/// Using path qualifiers like [`crate`], [`super`] or [`self`] is supported: `use crate::a::b;`.
+///
+/// Note that when the wildcard `*` is used on a type, it does not import its methods (though
+/// for `enum`s it imports the variants, as shown in the example below).
+///
+/// ```compile_fail
+/// # fn main() {
+/// enum ExampleEnum {
+/// VariantA,
+/// VariantB,
+/// }
///
-/// [not yet complete]: https://github.com/rust-lang/rust/issues/34601
+/// impl ExampleEnum {
+/// fn new() -> Self {
+/// Self::VariantA
+/// }
+/// }
+///
+/// use ExampleEnum::*;
+///
+/// // Compiles.
+/// let _ = VariantA;
+///
+/// // Does not compile !
+/// let n = new();
+/// # }
+/// ```
+///
+/// For more information on `use` and paths in general, see the [Reference].
+///
+/// The differences about paths and the `use` keyword between the 2015 and 2018 editions
+/// can also be found in the [Reference].
+///
+/// [`crate`]: keyword.crate.html
+/// [`self`]: keyword.self.html
+/// [`super`]: keyword.super.html
+/// [Reference]: ../reference/items/use-declarations.html
mod use_keyword {}
#[doc(keyword = "where")]