Merge remote-tracking branch 'upstream/master' into flow_utils

# Conflicts:
#	src/shared/utils/flattenChildren.js

docs/docs/05-reusable-components.md

@@ -213,7 +213,7 @@ class HelloMessage extends React.Component {
 ReactDOM.render(<HelloMessage name="Sebastian" />, mountNode);
 ```
 
-The API is similar to `React.createClass` with the exception of `getInitialState`. Instead of providing a separate `getInitialState` method, you set up your own `state` property in the constructor.
+The API is similar to `React.createClass` with the exception of `getInitialState`. Instead of providing a separate `getInitialState` method, you set up your own `state` property in the constructor. Just like the return value of `getInitialState`, the value you assign to `this.state` will be used as the initial state for your component.
 
 Another difference is that `propTypes` and `defaultProps` are defined as properties on the constructor instead of in the class body.
 

src/shared/utils/deprecated.js

@@ -7,6 +7,7 @@
  * of patent rights can be found in the PATENTS file in the same directory.
  *
  * @providesModule deprecated
+ * @flow
  */
 
 'use strict';
@@ -24,7 +25,13 @@ var warning = require('warning');
  * @param {function} fn The function to forward on to
  * @return {function} The function that will warn once and then call fn
  */
-function deprecated(fnName, newModule, newPackage, ctx, fn) {
+function deprecated<T: Function>(
+  fnName: string,
+  newModule: string,
+  newPackage: string,
+  ctx: mixed,
+  fn: T,
+): T {
   var warned = false;
   if (__DEV__) {
     var newFn = function() {
@@ -47,7 +54,12 @@ function deprecated(fnName, newModule, newPackage, ctx, fn) {
     };
     // We need to make sure all properties of the original fn are copied over.
     // In particular, this is needed to support PropTypes
-    return Object.assign(newFn, fn);
+    Object.assign(newFn, (fn: Object));
+
+    // Flow is not smart enough to figure out that newFn is of the same type as
+    // fn. Since we don't want to lose out the type of the function, casting
+    // to any and force flow to use T.
+    return ((newFn: any): T);
   }
 
   return fn;