Merge pull request #1817 from chenglou/docs-PureRenderMixin

[Docs] Document PureRenderMixin addon

_data/nav_docs.yml

@@ -55,6 +55,8 @@
       title: Cloning Components
     - id: update
       title: Immutability Helpers
+    - id: pure-render-mixin
+      title: PureRenderMixin
 - title: Reference
   items:
   - id: top-level-api

docs/09.6-update.md

@@ -4,6 +4,7 @@ title: Immutability Helpers
 layout: docs
 permalink: update.html
 prev: clone-with-props.html
+next: pure-render-mixin.html
 ---
 
 React lets you use whatever style of data management you want, including mutation. However, if you can use immutable data in performance-critical parts of your application it's easy to implement a fast `shouldComponentUpdate()` method to significantly speed up your app.

docs/09.7-pure-render-mixin.md

@@ -0,0 +1,30 @@
+---
+id: pure-render-mixin
+title: PureRenderMixin
+layout: docs
+permalink: pure-render-mixin.html
+prev: update.html
+---
+
+If your React component's render function is "pure" (in other words, it renders the same result given the same props and state), you can use this mixin for a considerable performance boost.
+
+Example:
+
+```js
+var PureRenderMixin = require('react').addons.PureRenderMixin;
+React.createClass({
+  mixins: [PureRenderMixin],
+
+  render: function() {
+    return <div className={this.props.className}>foo</div>;
+  }
+});
+```
+
+Under the hood, the mixin implements [shouldComponentUpdate](/react/docs/component-specs.html#updating-shouldcomponentupdate), in which it compares the current props and state with the next ones and returns `false` if the equalities pass.
+
+> Note:
+>
+> This only shallowly compares the objects. If these contain complex data structures, it may produce false-negatives for deeper differences. Only mix into components which have simple props and state, or use `forceUpdate()` when you know deep data structures have changed.
+>
+> Furthermore, `shouldComponentUpdate` skips updates for the whole component subtree. Make sure all the children components are also "pure".