Document difference between Children.map & Array.map

[dschep]

The two are not equivalent (which would be a users' expectation), for example:

> Children.map(this.props.children, child => ['foo', child]))
["foobar", Object]
> Children.toArray(children).map(child => ['foo', child])
[["foobar", Object]]

Information obtained from this comment:
#4410 (comment)

[facebook-github-bot]

Thank you for your pull request and welcome to our community. We require contributors to sign our Contributor License Agreement, and we don't seem to have you on file. In order for us to review and merge your code, please sign up at https://code.facebook.com/cla - and if you have received this in error or have any questions, please drop us a line at [email protected]. Thanks!

If you are contributing on behalf of someone else (eg your employer): the individual CLA is not sufficient - use https://developers.facebook.com/opensource/cla?type=company instead. Contact [email protected] if you have any questions.

[dschep]

This has been open for half a year with no feedback. This is a real difference in behavior that caught me by surprise that I can't find documented anywhere else. I'm going to close this PR soon if you don't want it tho, I don't need old PRs clogging up /pulls. It's just one sentence documentation so if it's an issue with @facebook's annoying CLA I'll just open an issue detailing the problem, which can easily be turned into documentation with out me "contributing" it.

[gaearon]

Sorry, we are in the middle of preparing a new release, and reviewing PRs (even one line changes) is not the top priority right now. We’ll do a cleanup pass over PRs and issues after the release, but the team is very small and needs to stay focused.

[gaearon]

Regarding your specific suggestion: I don’t think the sentence you added makes it a lot more clear what’s going on. It’s hard for me to suggest specific improvements without spending quite a bit of time to think about the wording. If you can suggest more possible wordings, we can probably pick one. Otherwise this will have to wait until we find more time to work on the docs again. Sorry about this. 😞

[gaearon]

(And no, you don’t need to close it. If docs don’t say the right thing, we should fix them, and this PR is a reminder. Even if we end up with a different wording.)

[dschep]

Yeah, I'm not sure what the best phrasing/copy is, I just wanted some clarification that Children.map has unexpected requirements / differences in behavior.

[jquense]

I would begin by trying to describe the actual behavior in your blurb, e.g. that returned arrays are "flattened" in the result. Overall though maybe the larger point is that the result of any React.Children methods produce an "opaque" data structure that is intended to passed to createElement, so no real assumptions about the shape or type returned should be assumed. That it returns an arrays, or a flat array is an implementation detail, not something that should be relied on by a consumer. toArray exists precisely for interop with the the outside world, so to speak.

[bvaughn]

Thank you for filing this PR!

I'm sorry to be the bearer of bad news, but the documentation and source code for reactjs.org now lives in a different repository: reactjs/reactjs.org. (For more info on why we made this move, see issue #11075.)

Would you be willing to re-open this PR on the new repo? I promise we'll review it quickly!