Improve docs for "factory function" syntax

[markerikson]

The current docs for the "factory function" syntax are not very clear, and also say that "most apps should never need this". We should rewrite that section, and also be sure to provide examples of using the factory function syntax.

For reference, discussion, and examples, see #279 , a Reddit comment I made with use cases and samples, and I think some of the articles in the Redux Performance section of my links list might discuss this.

[timdorr]

I would like this too. I've never been clear on what another level of indirection affords you when constructing these functions. I prefer the simplest object syntax, personally :)

[markerikson]

The short answer is that it provides a closure where you can create unique selector instances per component instance, so that the selectors memoize "properly" for that component.

[jimbolla]

I mostly use this for component-scoped memoization of selector results.

function mapState() {
  const getSomeProp= createSelector(...);
  return (state, props) => ({
    someProp: getSomeProp(state, props),
  });
}

[markerikson]

Right, that's the use case. What I'm saying is that the current doc page really doesn't actually describe how to do that or give examples. It hand-waves things, says, "you probably don't need to do what we just vaguely described anyway", and points to an old issue for examples. Since this is part of the API, it should be meaningfully documented.