Clarify behavior of Promise.reduce when initialValue is undefined.

[cscott]

If initialValue is a promise that resolves to undefined, it is treated as if initialValue was not supplied at all.

See #97.

[benjamingr]

👍 you might want to show the analogy of Array::reduce too

[petkaantonov]

It is already implied by "if initialValue is not given" which is what undefined means while null means a given empty value. If it's not clear then that should be communicated in general, not under reduce because all methods treat undefined as I just described.

[cscott]

@benjamingr it is deliberately different from Array::reduce: [1].reduce(function(){return 2;}, undefined) returns 2, but Promise.reduce([1], function(){return 2}, undefined) returns 1.

@petkaantonov in the above example it is clear to me that "initialValue is given". That is also the language of the es6 specification, https://people.mozilla.org/~jorendorff/es6-draft.html#sec-array.prototype.reduce, which says, "If an initialValue was provided in the call to reduce". You mean something different, and it is certainly not the case that "all methods treat undefined as I just described". Consider Function.bind(), for example, where f.bind(this) is very different from f.bind(this, undefined).

[petkaantonov]

Again, those are ES5 functions not ES6. I meant that the direction taken by ES6 is having these semantics for undefined.

For example when using the default parameter feature of ES6, passing undefined triggers the default parameter. So if function is defined as function a(param = 5) and you do a(undefined) it is same as a(5)

[cscott]

If you really wanted to clean up the api, then you should make initialValue a non-optional parameter. That is, reduce should always execute the supplied function exactly as many times as there are elements in the array. That would eliminate a huge potential source of bugs. Then I'd have no problem with the semantics you wish to use for undefined values.

But this particular pull request is just to make the docs match the current behavior. The harmony specs agree with me on this: "providing" or "giving" an argument is different from "argument is undefined". You seem to mean the latter, so the docs should say this clearly.