documentation feedback

[pwmckenna]

We finally made it to React 14, so I've gotten to use recompose in a large app for about a week now. Per the twitter request, here's a running list of thoughts...all of which I believe could be addressed through documentation. The functionality itself is amazing 🌲 🌲 🌲 . I'm happy to create PRs if these seem reasonable.

• onlyUpdateForPropTypes initially looks like an obvious win when combined with something like eslint-plugin-react's prop-types rule, but you can get yourself into trouble if you're passing your props through to children components using destructuring

<ChildComponent {...this.props}/>
// this will pass lint, but means your child component wil not update as expected
// if you wrap your component in onlyUpdateForPropTypes

• Links from the api back to the relavant examples on the main page would be nice. I'm constantly switching between the two.
• Put the api link at the top. It might be just me, but I ctrl+f api a dozen times a day.
• More examples. In particular, using withContext and getContext is super powerful, but it took me a bit to figure out. For instance, I end up propagating props that originated in my context. Perhaps a diagram showing the wrapping classes and how the context/props are changed at each level. In general, context is sort of hard to reason about, so all the hocs that deal with it could use a couple examples imo.
• Testing components that use hocs. This is probably unrelated to using recompose vs hand rolling hocs, but its way harder to test containers than dumb components. Maybe linking to enzyme examples or something would be enough.

[acdlite]

These are all great suggestions. I completely agree the docs needs lots of work.

Some docs PRs would be a good place to start!

[cerisier]

In addition to the feedback,
I found that many people actually believe that stateless components are treated as pure by React.
Would it be worth adding a line about this in the doc for the purpose of using the pure function ?

[acdlite]

I found that many people actually believe that stateless components are treated as pure by React.

Could you explain what you mean? Are you saying that people believe that React won't re-render a stateless component if the props haven't changed?

[cerisier]

Exactly. Tho this is only based on a couple exchanges with 2 devs who believed that as well.