polyfill and runtime transformer documentation is lacking

[Macil]

The old page about the runtime transformer seems to have disappeared. There's a new page about the runtime transformer, but it's less than useful. The setup page doesn't seem to mention the polyfill-or-runtime-transformer requirement at all. Nothing I found seems to link to the polyfill page, and that page doesn't do much to explain its necessity. The sentence "This will emulate a full ES6 environment" almost makes it sound like one could use babel or the polyfill to get ES6, instead of explaining that babel often must be used with the polyfill (or runtime transform). Issues like babel/babel#2654 seem inevitable for new users currently.

The polyfill page ought to explain its relationship to the runtime transformer and the necessity of one or the other being used for most es2015 transforms, and other pages (mainly the setup page and/or the transformers page) should link to it.

[tschaub]

I'm also interested in knowing how someone can know when the polyfill needs to be used. I was surprised, for example, to find that the es2015 presets implement instanceof with Symbol.

$ echo 'foo instanceof Bar' | babel --presets es2015
"use strict";

function _instanceof(left, right) { if (right != null && right[Symbol.hasInstance]) { return right[Symbol.hasInstance](left); } else { return left instanceof right; } }

_instanceof(foo, Bar);

I had originally assumed that the es2015 preset would result in ES2015 being transformed into ES5 (to the extent possible). I'd be happy to help update the documentation if someone could add detail here on when babel-polyfill is required. I'm sure it depends on the plugins being used. I imagine it would be useful to at least document when it is required using es2015 presets.

[tschaub]

I've prosed babel/babel#2784 to make it so instanceof doesn't require a Symbol polyfill.

[dburrows]

I agree this is an issue, I'm no longer sure when I need to use the polyfill and so I'm wary of upgrading to 6 - can't we just make a 'es2015-nopolyfill' or similar preset to make it 100% clear?

[dburrows]

Actually, will propose that on main repo, but still agree that this needs to be documented

[hzoo]

this is done