@yungsters

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.