From a5c4a382b7f0f9bb6a98001a6e5ffd9ab8ff3d70 Mon Sep 17 00:00:00 2001
From: iirelu <anna@bawk.space>
Date: Sun, 9 Sep 2018 15:44:59 +0200
Subject: [PATCH] Expand fn keyword docs

---
 src/libstd/keyword_docs.rs | 66 ++++++++++++++++++++++++++++++++++----
 1 file changed, 59 insertions(+), 7 deletions(-)

diff --git a/src/libstd/keyword_docs.rs b/src/libstd/keyword_docs.rs
index a09917afbad..0cf524ab0dc 100644
--- a/src/libstd/keyword_docs.rs
+++ b/src/libstd/keyword_docs.rs
@@ -223,21 +223,73 @@ mod extern_keyword { }
 
 #[doc(keyword = "fn")]
 //
-/// The `fn` keyword.
+/// The keyword for defining functions.
 ///
-/// The `fn` keyword is used to declare a function.
+/// Functions are the primary way code is executed within Rust. Function blocks, usually just
+/// called functions, can be defined in a variety of different places and be assigned many
+/// different attributes and modifiers.
 ///
-/// Example:
+/// Standalone functions that just sit within a module not attached to anything else are common,
+/// but most functions will end up being inside [`impl`] blocks, either on another type itself, or
+/// as a trait impl for that type.
 ///
 /// ```rust
-/// fn some_function() {
-///     // code goes in here
+/// fn standalone_function() {
+///     // code
+/// }
+///
+/// pub fn public_thing(argument: bool) -> String {
+///     // code
+///     # "".to_string()
+/// }
+///
+/// struct Thing {
+///     foo: i32,
+/// }
+///
+/// impl Thing {
+///     pub fn new() -> Self {
+///         Self {
+///             foo: 42,
+///         }
+///     }
 /// }
 /// ```
 ///
-/// For more information about functions, take a look at the [Rust Book][book].
+/// See docs on [`impl`] and [`self`] for relevant details on those.
 ///
-/// [book]: https://doc.rust-lang.org/book/second-edition/ch03-03-how-functions-work.html
+/// In addition to presenting fixed types in the form of `fn name(arg: type, ..) -> return_type`,
+/// functions can also declare a list of type parameters along with trait bounds that they fall
+/// into.
+///
+/// ```rust
+/// fn generic_function<T: Clone>(x: T) -> (T, T, T) {
+///     (x.clone(), x.clone(), x.clone())
+/// }
+///
+/// fn generic_where<T>(x: T) -> T
+///     where T: std::ops::Add<Output=T> + Copy
+/// {
+///     x + x + x
+/// }
+/// ```
+///
+/// Declaring trait bounds in the angle brackets is functionally identical to using a [`where`]
+/// clause, but `where` is preferred due to it being easier to understand at a glance.
+///
+/// Along with being made public via [`pub`], `fn` can also have an [`extern`] added for use in
+/// FFI.
+///
+/// For more information on the various types of functions and how they're used, consult the [Rust
+/// book] or the [Reference].
+///
+/// [`impl`]: keyword.impl.html
+/// [`self`]: keyword.self.html
+/// [`where`]: keyword.where.html
+/// [`pub`]: keyword.pub.html
+/// [`extern`]: keyword.extern.html
+/// [Rust book]: https://doc.rust-lang.org/book/second-edition/ch03-03-how-functions-work.html
+/// [Reference]: https://doc.rust-lang.org/reference/items/functions.html
 mod fn_keyword { }
 
 #[doc(keyword = "let")]