[heycam/webidl] Add an informative section on overloads vs. unions/optional (#307)

After I understand this better---see https://github.com/jsdom/webidl2js/issues/29#issuecomment-278347717 --- I'd like to contribute a non-normative section talking about the differences between using overloads for your APIs versus using unions/optional. Potential points to cover:

- Examples of cases that cannot be expressed in one but can in the other (or, if no such cases exist, examples where it is much easier to express in one)
- Examples of non-obvious semantic differences between an interface written using overloads vs. one written using unions/optional.
- An explanation of how the prose algorithms for the two different styles are intended to be written---i.e., overloads you should have a separate prose algorithm per overload, whereas unions/optional should have a single algorithm. It's worth adding a comment here about how overloads map well to C++ via the binding layer, and should be thought of that way; they don't as obviously map to JavaScript.
- Some small encouragement to use unions/optional instead of overloads when possible, since the spec machinery involved is much less complicated and is easier to reason about.

I'm hoping for some help on the examples; see the conversions linked to above.

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/heycam/webidl/issues/307