From 01defa40c551540e5d483c494f0e585f5943a92c Mon Sep 17 00:00:00 2001
From: Havvy <ryan.havvy@gmail.com>
Date: Tue, 31 Jul 2018 20:50:25 -0700
Subject: [PATCH] Add optimization hints section to attributes

---
 src/attributes.md | 45 +++++++++++++++++++++++++++++++--------------
 1 file changed, 31 insertions(+), 14 deletions(-)

diff --git a/src/attributes.md b/src/attributes.md
index fca8d95cf..3cd103496 100644
--- a/src/attributes.md
+++ b/src/attributes.md
@@ -126,8 +126,6 @@ names have meaning.
   - `ignore` - indicates that this test function is disabled.
 - `should_panic` - indicates that this test function should panic, inverting the
   success condition.
-- `cold` - The function is unlikely to be executed, so optimize it (and calls
-  to it) differently.
 
 ## FFI attributes
 
@@ -405,25 +403,43 @@ When used on a function in an implementation, the attribute does nothing.
 The `must_use` attribute may also include a message by using
 `#[must_use = "message"]`. The message will be given alongside the warning.
 
-### Inline attribute
+### Optimization Hints
 
-The inline attribute suggests that the compiler should place a copy of
-the function or static in the caller, rather than generating code to
-call the function or access the static where it is defined.
+The `cold` and `inline` attributes give suggestions to the compiler to compile
+your code in a way that may be faster than what it would do without the hint.
+The attributes are only suggestions, and the compiler may choose to ignore it.
 
-The compiler automatically inlines functions based on internal heuristics.
-Incorrectly inlining functions can actually make the program slower, so it
-should be used with care.
+#### `inline` Attribute
 
-`#[inline]` and `#[inline(always)]` always cause the function to be serialized
-into the crate metadata to allow cross-crate inlining.
+The *`inline` attribute* suggests to the compiler that it should place a copy of
+the attributed function in the caller, rather than generating code to call the
+function where it is defined.
 
-There are three different types of inline attributes:
+This attribute can be used on [functions] and function prototypes, although it
+does not do anything on function prototypes. When this attribute is applied to
+a function in a [trait], it applies only to that function when used as a default
+function for a trait implementation and not to all trait implementations.
+
+> ***Note***: The compiler automatically inlines functions based on internal
+> heuristics. Incorrectly inlining functions can actually make the program
+> slower, so this attibute should be used with care.
+
+There are three ways of using the inline attribute:
 
 * `#[inline]` hints the compiler to perform an inline expansion.
 * `#[inline(always)]` asks the compiler to always perform an inline expansion.
 * `#[inline(never)]` asks the compiler to never perform an inline expansion.
 
+#### `cold` Attribute
+
+The *`cold` attribute* suggests to the compiler that the attributed function is
+unlikely to be called.
+
+This attribute can be used on [functions] and function prototypes, although it
+does not do anything on function prototypes. When this attribute is applied to
+a function in a [trait], it applies only to that function when used as a default
+function for a trait implementation and not to all trait implementations.
+
 ### `derive`
 
 The `derive` attribute allows certain traits to be automatically implemented
@@ -454,7 +470,7 @@ impl<T: PartialEq> PartialEq for Foo<T> {
 }
 ```
 
-You can implement `derive` for your own type through [procedural macros].
+You can implement `derive` for your own traits through [procedural macros].
 
 [Doc comments]: comments.html#doc-comments
 [The Rustdoc Book]: ../rustdoc/the-doc-attribute.html
@@ -482,4 +498,5 @@ You can implement `derive` for your own type through [procedural macros].
 [match expressions]: expressions/match-expr.html
 [external blocks]: items/external-blocks.html
 [items]: items.html
-[conditional compilation]: conditional-compilation.html
\ No newline at end of file
+[conditional compilation]: conditional-compilation.html
+[trait]: items/traits.html
\ No newline at end of file