From f586c58f960f6efb994a9fa325c524e1150844ad Mon Sep 17 00:00:00 2001
From: petehunt <floydophone@gmail.com>
Date: Thu, 30 May 2013 14:45:22 -0700
Subject: [PATCH] @yungsters

---
 docs/docs/mixins.md | 16 ++++++++++------
 1 file changed, 10 insertions(+), 6 deletions(-)

diff --git a/docs/docs/mixins.md b/docs/docs/mixins.md
index 1f78ebe4299ec..65acef6ddfeae 100644
--- a/docs/docs/mixins.md
+++ b/docs/docs/mixins.md
@@ -6,10 +6,10 @@ prev: advanced-components.html
 next: api.html
 ---
 
-Mixins allow code to be shared between multiple React components. They're pretty similar to mixins in Python or traits in PHP. Let's look at a simple example:
+Mixins allow code to be shared between multiple React components. They are pretty similar to mixins
+in Python or traits in PHP. Let's look at a simple example:
 
 ```javascript
-// mixins-simple.js
 var MyMixin = {
   getMessage: function() {
     return 'hello world';
@@ -24,10 +24,13 @@ var MyComponent = React.createClass({
 });
 ```
 
-A class can use multiple mixins. Multiple mixins can also override any of the lifecycle methods and they'll be called for each mixin. Here's an example:
+A class can use multiple mixins, but no two mixins can define the same method. Two mixins can, however,
+implement the same [lifecycle method](component-lifecycle.html). In this case, each implementation will be invoked one after another.
+
+The only exception is the `shouldComponentUpdate` lifecycle method. This method may only be implemented once
+(either by a mixin or by the component).
 
 ```javascript
-// mixins-advanced.js
 var Mixin1 = {
   componentDidMount: function() {
     console.log('Mixin1.componentDidMount()');
@@ -49,7 +52,7 @@ var MyComponent = React.createClass({
 });
 ```
 
-When MyComponent is mounted in the page the following text will print to the console:
+When `MyComponent` is mounted into the page, the following text will print to the console:
 
 ```
 Mixin1.componentDidMount()
@@ -58,4 +61,5 @@ Mixin2.componentDidMount()
 
 ## When should you use mixins?
 
-In general, add a mixin whenever you want a component to share some utility methods, public interface, or lifecycle behavior. Often it's appropriate to use them as you would use a superclass in another OOP language.
+In general, add a mixin whenever you want a component to share some utility methods, public interface,
+or lifecycle behavior. Often it's appropriate to use them as you would use a superclass in another OOP language.