Merge pull request #1100 from plievone/mapchildren-docs

Fix docs for React.Children.map, .forEach, .only.

Author: zpao

docs/docs/ref-01-top-level-api.md

@@ -18,26 +18,26 @@ next: component-api.html
 #### React.Children.map
 
 ```javascript
-array React.Children.map(object children, function fn [, object context])
+object React.Children.map(object children, function fn [, object context])
 ```
 
-Invoke `fn` on every immediate child contained within `children` with `this` set to `context`. If `children` is a nested object or array it will be traversed: `fn` will never be passed the container objects.
+Invoke `fn` on every immediate child contained within `children` with `this` set to `context`. If `children` is a nested object or array it will be traversed: `fn` will never be passed the container objects. If children is `null` or `undefined` returns `null` or `undefined` rather than an empty object.
 
 #### React.Children.forEach
 
 ```javascript
 React.Children.forEach(object children, function fn [, object context])
 ```
 
-Like `React.Children.map()` but does not return an array.
+Like `React.Children.map()` but does not return an object.
 
-#### React.children.only()
+#### React.Children.only
 
 ```javascript
 object React.Children.only(object children)
 ```
 
-Return the only child in `children`. If `children` is a nested object or array it will be traversed.
+Return the only child in `children`. Throws otherwise.
 
 
 ### React.DOM

src/utils/ReactChildren.js

@@ -52,7 +52,7 @@ function forEachSingleChild(traverseContext, child, name, i) {
  * The provided forEachFunc(child, index) will be called for each
  * leaf child.
  *
- * @param {array} children
+ * @param {?*} children Children tree container.
  * @param {function(*, int)} forEachFunc.
  * @param {*} forEachContext Context for forEachContext.
  */
@@ -107,10 +107,10 @@ function mapSingleChildIntoContext(traverseContext, child, name, i) {
  * TODO: This may likely break any calls to `ReactChildren.map` that were
  * previously relying on the fact that we guarded against null children.
  *
- * @param {array} children
+ * @param {?*} children Children tree container.
  * @param {function(*, int)} mapFunction.
  * @param {*} mapContext Context for mapFunction.
- * @return {array} mirrored array with mapped children.
+ * @return {object} Object containing the ordered map of results.
  */
 function mapChildren(children, func, context) {
   if (children == null) {