Document the type keyword

1 files changed, 26 insertions, 2 deletions

diff --git a/src/libstd/keyword_docs.rs b/src/libstd/keyword_docs.rs
index d972cf6db18..3b493c4244d 100644
--- a/src/libstd/keyword_docs.rs
+++ b/src/libstd/keyword_docs.rs
@@ -1463,9 +1463,33 @@ mod true_keyword {}
 //
 /// Define an alias for an existing type.
 ///
-/// The documentation for this keyword is [not yet complete]. Pull requests welcome!
+/// The syntax is `type Name = ExistingType;`.
 ///
-/// [not yet complete]: https://github.com/rust-lang/rust/issues/34601
+/// # Examples
+///
+/// `type` does **not** create a new type:
+///
+/// ```rust
+/// type Meters = u32;
+/// type Kilograms = u32;
+///
+/// let m: Meters = 3;
+/// let k: Kilograms = 3;
+///
+/// assert_eq!(m, k);
+/// ```
+///
+/// In traits, using `type` allows the usage of an associated type without
+/// knowing about it when declaring the [`trait`]:
+///
+/// ```rust
+/// trait Iterator {
+///     type Item;
+///     fn next(&mut self) -> Option<Self::Item>;
+/// }
+/// ```
+///
+/// [`trait`]: keyword.trait.html
 mod type_keyword {}
 
 #[doc(keyword = "unsafe")]