Re: [heycam/webidl] Add a section on overloads vs. union/optional (#426)

annevk commented on this pull request.



> +Additionally, there are semantic differences as well. [=Union types=] are usually used in the sense
+that "any of the types would work in about the same way". In contrast, [=overloaded=] operations are
+designed to map well to language features such as C++ overloading, and are usually a better fit for
+operations with more substantial differences in what they do given arguments of different types.
+However, in most cases, operations with such substantial differences are best off with different
+names to avoid confusion for Web developers, since the ECMAScript language does not provide
+language-level overloading. As such, overloads are rarely appropriate for new APIs, instead often
+appearing in legacy APIs or in specialized circumstances.
+
+That being said, we offer the following recommendations and examples in case of difficulties to
+determine what Web IDL language feature to use:
+
+*   In the unusual case where the operation must return values of different types for different
+    argument types, [=overloaded|overloading=] should be used. <span class="note">This is almost
+    never appropriate API design, and separate operations with distinct names should be used for
+    such cases.</span>

You cannot have should in a note. You probably do not want to use a note here.

-- 
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/pull/426#pullrequestreview-60510473