Merge pull request #5599 from zramaekers/shallow-compare-docs

Add documentation for shallowCompare addon

docs/_data/nav_docs.yml

@@ -65,6 +65,8 @@
       title: PureRenderMixin
     - id: perf
       title: Performance Tools
+    - id: shallow-compare
+      title: Shallow Compare
   - id: advanced-performance
     title: Advanced Performance
   - id: context

docs/docs/10-addons.md

@@ -14,6 +14,7 @@ The React add-ons are a collection of useful utility modules for building React
 - [`createFragment`](create-fragment.html), to create a set of externally-keyed children.
 - [`update`](update.html), a helper function that makes dealing with immutable data in JavaScript easier.
 - [`PureRenderMixin`](pure-render-mixin.html), a performance booster under certain situations.
+- [`shallowCompare`](shallow-compare.html), a helper function that performs a shallow comparison for props and state in a component to decide if a component should update.
 
 The add-ons below are in the development (unminified) version of React only:
 

docs/docs/10.10-shallow-compare.md

@@ -0,0 +1,32 @@
+---
+id: shallow-compare
+title: Shallow Compare
+permalink: shallow-compare.html
+prev: perf.html
+next: advanced-performance.html
+---
+
+`shallowCompare` is a helper function to achieve the same functionality as `PureRenderMixin` while using ES6 classes with React.
+
+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 helper function for a performance boost in some cases.
+
+Example:
+
+```js
+var shallowCompare = require('react-addons-shallow-compare');
+export class SampleComponent extends React.Component {
+  shouldComponentUpdate(nextProps, nextState) {
+    return shallowCompare(this, nextProps, nextState);
+  }
+
+  render() {
+    return <div className={this.props.className}>foo</div>;
+  }
+}
+```
+
+`shallowCompare` performs a shallow equality check on the current `props` and `nextProps` objects as well as the current `state` and `nextState` objects.  
+It does this by iterating on the keys of the objects being compared and returning false when the value of a key in each object are not strictly equal.
+
+`shallowCompare` returns `true` if the shallow comparison for props or state fails and therefore the component should update.  
+`shallowCompare` returns `false` if the shallow comparison for props and state both pass and therefore the component does not need to update.

docs/docs/10.9-perf.md

@@ -3,7 +3,7 @@ id: perf
 title: Performance Tools
 permalink: perf.html
 prev: pure-render-mixin.html
-next: advanced-performance.html
+next: shallow-compare.html
 ---
 
 React is usually quite fast out of the box. However, in situations where you need to squeeze every ounce of performance out of your app, it provides a [shouldComponentUpdate](/react/docs/component-specs.html#updating-shouldcomponentupdate) hook where you can add optimization hints to React's diff algorithm.

docs/docs/11-advanced-performance.md

@@ -2,7 +2,7 @@
 id: advanced-performance
 title: Advanced Performance
 permalink: advanced-performance.html
-prev: perf.html
+prev: shallow-compare.html
 next: context.html
 ---