[Docs] Add Example For React.Children.map

[adeelibr]

For https://reactjs.org/docs/react-api.html#reactchildrenmap to help illustrate as to what it does, can we kindly add an example for something like this.

const Value = ({ value }) => <p>{value}</p>

const PropsInjector = ({ children }) => React.Children.map(children, child => {
  return React.cloneElement(child, { value: 'some_value'  });
});

const App = () => (
   <PropsInjector>
        <Value />
        <Value />
    </PropsInjector>
)

I don't know if this might be an acceptable example for React.Children.map, but I would love to hear some feedback if possible.

The current documentation doesn't have a an example on how React.Children.map can be used & it doesn't make sense for someone like me

As per docs: React.Children.map(children, function[(thisArg)])

For someone like me I got very confused function[(thisArg)] when I read this & didn't know on how I could use it.

I am more then happy to make a PR for adding this example & or any better example if someone can suggest.

[rowanmoul]

Examples are nice. I'd just like to see a proper list of arguments for this method and the similar forEach one. As @adeelibr said, the current docs do not explain how to use the methods. I had to go find the implementation in the code to discover what arguments I could expect in the mapFunction. If I have some time later I would be happy to submit a PR for this, but I'm not clear on what the key is vs the index in the mapFunction, so I would have a hard time giving a good explanation.

/**
 * Maps children that are typically specified as `props.children`.
 *
 * See https://reactjs.org/docs/react-api.html#reactchildrenmap
 *
 * The provided mapFunction(child, key, index) will be called for each
 * leaf child.
 *
 * @param {?*} children Children tree container.
 * @param {function(*, int)} func The map function.
 * @param {*} context Context for mapFunction.
 * @return {object} Object containing the ordered map of results.
 */
function mapChildren(children, func, context) {

To add to the confusion, the @types/react package defines the map method as taking a mapFunction with only two arguments: the Child, and the index