Document ReactDOM.unstable_batchedUpdates

[graue]

Took a stab at documenting this. Let me know what you think.

Fixes #3570

[graue]

[jimfb]

We generally don't document the unstable_ features.

Also, FWIW, this function is really only useful to react framework authors (ie. not the general public component authors), so top-level api docs are probably too prominent. Most of the framework authors are tied into github and know how to find the unstable/undocumented functionality.

[graue]

Can I get a second opinion on this? @spicyj ?

We saw an over 25% speedup in a part of Instagram.com after using this hook, so I disagree with the notion that it's only useful to framework authors. This should be accessible to everyone to eke out perf wins.

[sophiebits]

25% faster on what sort of operation?

[mridgway]

We used this for batching Flux change events with a lot of success. I agree it shouldn't be documented unless it becomes "stable", but I would argue that it's useful enough to become a top level API.

[sophiebits]

I don't feel strongly either way about documenting it so I am willing to follow @jimfb's lead in saying no.

We do want to move to automatically batching everything, at which time this hook is moot. Until then it will probably stay where it is.

[graue]

On rerendering when you navigate to a new post. This is easy to document (I've already done it), will enable people to write more performant apps and ship better UX, and is easily codemodded away if and when automatic batching comes to pass (which is probably at least months away from being in a release, yes?). Why not?

[jimfb]

On rerendering when you navigate to a new post.

This doesn't help me to understand. Specifically, what operations is the app doing that results in a benefit from batching (and why is the app doing whatever operations it is doing). A single rerender would not benefit from batching.

This is easy to document (I've already done it), will enable people to write more performant apps and ship better UX, and is easily codemodded away if and when automatic batching comes to pass (which is probably at least months away from being in a release, yes?). Why not?

It is not about how easy/hard it is to document - it's about the stability guarantees we're making. If we want to release this as stable, we could consider that, but we shouldn't document something that is unstable_. We also shouldn't release something as stable if we're just going to get rid of it in a couple months.

[graue]

@jimfb, N>1 Flux stores emit change events. Naively, this leads to N renders. You skipped over my key point as to why the benefits of documenting outweigh the downsides:

is easily codemodded away if and when automatic batching comes to pass (which is probably at least months away from being in a release)

[mxstbr]

@graue I'd be interested in a code snippet how you did that.

[graue]

@mxstbr:

class MyDispatcher extends Dispatcher {
  constructor() {
    super();
    this._actuallyDispatch = Dispatcher.prototype.dispatch.bind(this);
  }
  dispatch(payload) {
    ReactDOM.unstable_batchedUpdates(this._actuallyDispatch, payload);
  }
}
export default new MyDispatcher();

This is from memory, may not be 100% right.

[jayarjo]

We do want to move to automatically batching everything, at which time this hook is moot. Until then it will probably stay where it is.

@sophiebits did you finally move to automatically batching everything?

[gaearon]

Not yet.