Document React.pure

Author: sebmarkbage

content/docs/reference-react.md

@@ -26,6 +26,10 @@ React components let you split the UI into independent, reusable pieces, and thi
 
 If you don't use ES6 classes, you may use the `create-react-class` module instead. See [Using React without ES6](/docs/react-without-es6.html) for more information.
 
+React components can also be defined as functions which can be wrapped by further functionality.
+
+- [`React.pure`](#reactpure)
+
 ### Creating React Elements
 
 We recommend [using JSX](/docs/introducing-jsx.html) to describe what your UI should look like. Each JSX element is just syntactic sugar for calling [`React.createElement()`](#createelement). You will not typically invoke the following methods directly if you are using JSX.
@@ -88,6 +92,42 @@ If your React component's `render()` function renders the same result given the
 
 * * *
 
+### `React.pure`
+
+```javascript
+const MyComponent = React.pure(function(props) {
+  /* render using props */
+});
+```
+
+`React.pure` is a [higher order component](/docs/higher-order-components.html). It's similar to [`React.PureComponent`](#reactpurecomponent) but for function components instead of classes.
+
+If your function component renders the same result given the same props, you can wrap it in a call to `React.pure` for a performance boost in some cases by memoizing the result.
+
+By default it will only shallowly compare complex objects in the props object. If you want control over the comparison, you can also provide a custom comparison function as the second argument.
+
+```javascript
+function render(props) {
+  /* render using props */
+}
+function equals(prevProps, nextProps) {
+  /*
+  return true if passing nextProps to render would return
+  the same result as passing prevProps to render,
+  otherwise return false
+  */
+}
+const MyComponent = React.pure(render, equals);
+```
+
+This method only exists as a **[performance optimization](/docs/optimizing-performance.html).** Do not rely on it to "prevent" a rendering, as this can lead to bugs.
+
+> Note
+>
+> Unlike the [`shouldComponentUpdate()`](/docs/react-component.html#shouldcomponentupdate) method on class components, the `areEqual` function returns `true` if the props are equal and `false` if the props are not equal. This is the inverse from `shouldComponentUpdate`.
+
+* * *
+
 ### `createElement()`
 
 ```javascript