{"action":"created","comment":{"url":"https://api.github.com/repos/heycam/webidl/pulls/comments/136909997","pull_request_review_id":60511977,"id":136909997,"diff_hunk":"@@ -3341,6 +3341,249 @@ be the same.\n </div>\n \n \n+<h5 id=\"idl-overloading-vs-union\">Overloading vs. union types</h5>\n+\n+<i>This section is informative.</i>\n+\n+<div class=\"non-normative\">\n+\n+For specifications defining IDL [=operations=], it may seem that [=overloaded|overloads=] and a\n+combination of [=union types=] and [=optional arguments=] have some feature overlap.\n+\n+It is first important to note that [=overloaded|overloads=] may have different behaviors than\n+[=union types=] or [=optional arguments=], and one <em>cannot</em> be fully defined using the other\n+(unless, of course, additional prose is provided, which can defeat the purpose of the Web IDL type\n+system). For example, consider the {{CanvasDrawPath/stroke()}} operations defined on the\n+{{CanvasDrawPath}} interface [[HTML]]:\n+\n+<pre highlight=\"webidl\">\n+    interface CanvasDrawPathExcerpt {\n+      void stroke();\n+      void stroke(Path2D path);\n+    };\n+</pre>\n+\n+Per the ECMAScript language binding, calling <code>stroke(undefined)</code> on an object\n+implementing <code class=\"idl\">CanvasDrawPathExcerpt</code> would attempt to call the second\n+overload, yielding a {{TypeError}} since <emu-val>undefined</emu-val> cannot be <a\n+href=\"#es-to-interface\">converted</a> to a {{Path2D}}. However, if the operations were instead\n+defined with [=optional arguments=] and merged into one,\n+\n+<pre highlight=\"webidl\">\n+    interface CanvasDrawPathExcerptOptional {\n+      void stroke(optional Path2D path);\n+    };\n+</pre>\n+\n+the [=overload resolution algorithm=] would treat the <var ignore>path</var> argument as [=not\n+present=] given the same call <code>stroke(undefined)</code>, and not throw any exceptions.\n+\n+Note: For this particular example, the latter behavior is actually what Web developers would\n+generally expect. If {{CanvasDrawPath}} were to be designed today, [=optional arguments=] would be\n+used for <code class=\"idl\">stroke()</code>.\n+\n+Additionally, there are semantic differences as well. [=Union types=] are usually used in the sense\n+that \"any of the types would work in about the same way\". In contrast, [=overloaded=] operations are\n+designed to map well to language features such as C++ overloading, and are usually a better fit for\n+operations with more substantial differences in what they do given arguments of different types.\n+However, in most cases, operations with such substantial differences are best off with different\n+names to avoid confusion for Web developers, since the ECMAScript language does not provide\n+language-level overloading. As such, overloads are rarely appropriate for new APIs, instead often\n+appearing in legacy APIs or in specialized circumstances.\n+\n+That being said, we offer the following recommendations and examples in case of difficulties to\n+determine what Web IDL language feature to use:\n+\n+*   In the unusual case where the operation must return values of different types for different\n+    argument types, [=overloaded|overloading=] should be used. <span class=\"note\">This is almost\n+    never appropriate API design, and separate operations with distinct names should be used for\n+    such cases.</span>","path":"index.bs","position":60,"original_position":60,"commit_id":"53005fc0277db96110839d5c028253e635e52919","original_commit_id":"53005fc0277db96110839d5c028253e635e52919","user":{"login":"TimothyGu","id":1538624,"avatar_url":"https://avatars2.githubusercontent.com/u/1538624?v=4","gravatar_id":"","url":"https://api.github.com/users/TimothyGu","html_url":"https://github.com/TimothyGu","followers_url":"https://api.github.com/users/TimothyGu/followers","following_url":"https://api.github.com/users/TimothyGu/following{/other_user}","gists_url":"https://api.github.com/users/TimothyGu/gists{/gist_id}","starred_url":"https://api.github.com/users/TimothyGu/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/TimothyGu/subscriptions","organizations_url":"https://api.github.com/users/TimothyGu/orgs","repos_url":"https://api.github.com/users/TimothyGu/repos","events_url":"https://api.github.com/users/TimothyGu/events{/privacy}","received_events_url":"https://api.github.com/users/TimothyGu/received_events","type":"User","site_admin":false},"body":"This entire section is non-normative. Does that mean I'm not allowed to use the RFC keywords anywhere in this section? What other words would you suggest?","created_at":"2017-09-05T07:15:32Z","updated_at":"2017-09-05T07:15:33Z","html_url":"https://github.com/heycam/webidl/pull/426#discussion_r136909997","pull_request_url":"https://api.github.com/repos/heycam/webidl/pulls/426","author_association":"CONTRIBUTOR","_links":{"self":{"href":"https://api.github.com/repos/heycam/webidl/pulls/comments/136909997"},"html":{"href":"https://github.com/heycam/webidl/pull/426#discussion_r136909997"},"pull_request":{"href":"https://api.github.com/repos/heycam/webidl/pulls/426"}},"in_reply_to_id":136908683},"pull_request":{"url":"https://api.github.com/repos/heycam/webidl/pulls/426","id":137589733,"html_url":"https://github.com/heycam/webidl/pull/426","diff_url":"https://github.com/heycam/webidl/pull/426.diff","patch_url":"https://github.com/heycam/webidl/pull/426.patch","issue_url":"https://api.github.com/repos/heycam/webidl/issues/426","number":426,"state":"open","locked":false,"title":"Add a section on overloads vs. union/optional","user":{"login":"TimothyGu","id":1538624,"avatar_url":"https://avatars2.githubusercontent.com/u/1538624?v=4","gravatar_id":"","url":"https://api.github.com/users/TimothyGu","html_url":"https://github.com/TimothyGu","followers_url":"https://api.github.com/users/TimothyGu/followers","following_url":"https://api.github.com/users/TimothyGu/following{/other_user}","gists_url":"https://api.github.com/users/TimothyGu/gists{/gist_id}","starred_url":"https://api.github.com/users/TimothyGu/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/TimothyGu/subscriptions","organizations_url":"https://api.github.com/users/TimothyGu/orgs","repos_url":"https://api.github.com/users/TimothyGu/repos","events_url":"https://api.github.com/users/TimothyGu/events{/privacy}","received_events_url":"https://api.github.com/users/TimothyGu/received_events","type":"User","site_admin":false},"body":"Fixes #307.\n\n\n<!--\n    This comment and the below content is programatically generated.\n    You may add a comma-separated list of anchors you'd like a\n    direct link to below (e.g. #idl-serializers, #idl-sequence):\n\n    Don't remove this comment or modify anything below this line.\n    If you don't want a preview generated for this pull request,\n    just replace the whole of this comment's content by \"no preview\"\n    and remove what's below.\n-->\n***\n[Preview](https://s3.amazonaws.com/pr-preview/TimothyGu/webidl/overloads-vs-union-optional.html) | [Diff](https://s3.amazonaws.com/pr-preview/heycam/webidl/f869be8...TimothyGu:53005fc.html)","created_at":"2017-08-25T02:39:00Z","updated_at":"2017-09-05T07:15:33Z","closed_at":null,"merged_at":null,"merge_commit_sha":"8523d528d10e6cda173d1f57b8dd6e2e64854cde","assignee":null,"assignees":[],"requested_reviewers":[],"milestone":null,"commits_url":"https://api.github.com/repos/heycam/webidl/pulls/426/commits","review_comments_url":"https://api.github.com/repos/heycam/webidl/pulls/426/comments","review_comment_url":"https://api.github.com/repos/heycam/webidl/pulls/comments{/number}","comments_url":"https://api.github.com/repos/heycam/webidl/issues/426/comments","statuses_url":"https://api.github.com/repos/heycam/webidl/statuses/53005fc0277db96110839d5c028253e635e52919","head":{"label":"TimothyGu:overloads-vs-union-optional","ref":"overloads-vs-union-optional","sha":"53005fc0277db96110839d5c028253e635e52919","user":{"login":"TimothyGu","id":1538624,"avatar_url":"https://avatars2.githubusercontent.com/u/1538624?v=4","gravatar_id":"","url":"https://api.github.com/users/TimothyGu","html_url":"https://github.com/TimothyGu","followers_url":"https://api.github.com/users/TimothyGu/followers","following_url":"https://api.github.com/users/TimothyGu/following{/other_user}","gists_url":"https://api.github.com/users/TimothyGu/gists{/gist_id}","starred_url":"https://api.github.com/users/TimothyGu/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/TimothyGu/subscriptions","organizations_url":"https://api.github.com/users/TimothyGu/orgs","repos_url":"https://api.github.com/users/TimothyGu/repos","events_url":"https://api.github.com/users/TimothyGu/events{/privacy}","received_events_url":"https://api.github.com/users/TimothyGu/received_events","type":"User","site_admin":false},"repo":{"id":99519463,"name":"webidl","full_name":"TimothyGu/webidl","owner":{"login":"TimothyGu","id":1538624,"avatar_url":"https://avatars2.githubusercontent.com/u/1538624?v=4","gravatar_id":"","url":"https://api.github.com/users/TimothyGu","html_url":"https://github.com/TimothyGu","followers_url":"https://api.github.com/users/TimothyGu/followers","following_url":"https://api.github.com/users/TimothyGu/following{/other_user}","gists_url":"https://api.github.com/users/TimothyGu/gists{/gist_id}","starred_url":"https://api.github.com/users/TimothyGu/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/TimothyGu/subscriptions","organizations_url":"https://api.github.com/users/TimothyGu/orgs","repos_url":"https://api.github.com/users/TimothyGu/repos","events_url":"https://api.github.com/users/TimothyGu/events{/privacy}","received_events_url":"https://api.github.com/users/TimothyGu/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/TimothyGu/webidl","description":"Web IDL","fork":true,"url":"https://api.github.com/repos/TimothyGu/webidl","forks_url":"https://api.github.com/repos/TimothyGu/webidl/forks","keys_url":"https://api.github.com/repos/TimothyGu/webidl/keys{/key_id}","collaborators_url":"https://api.github.com/repos/TimothyGu/webidl/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/TimothyGu/webidl/teams","hooks_url":"https://api.github.com/repos/TimothyGu/webidl/hooks","issue_events_url":"https://api.github.com/repos/TimothyGu/webidl/issues/events{/number}","events_url":"https://api.github.com/repos/TimothyGu/webidl/events","assignees_url":"https://api.github.com/repos/TimothyGu/webidl/assignees{/user}","branches_url":"https://api.github.com/repos/TimothyGu/webidl/branches{/branch}","tags_url":"https://api.github.com/repos/TimothyGu/webidl/tags","blobs_url":"https://api.github.com/repos/TimothyGu/webidl/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/TimothyGu/webidl/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/TimothyGu/webidl/git/refs{/sha}","trees_url":"https://api.github.com/repos/TimothyGu/webidl/git/trees{/sha}","statuses_url":"https://api.github.com/repos/TimothyGu/webidl/statuses/{sha}","languages_url":"https://api.github.com/repos/TimothyGu/webidl/languages","stargazers_url":"https://api.github.com/repos/TimothyGu/webidl/stargazers","contributors_url":"https://api.github.com/repos/TimothyGu/webidl/contributors","subscribers_url":"https://api.github.com/repos/TimothyGu/webidl/subscribers","subscription_url":"https://api.github.com/repos/TimothyGu/webidl/subscription","commits_url":"https://api.github.com/repos/TimothyGu/webidl/commits{/sha}","git_commits_url":"https://api.github.com/repos/TimothyGu/webidl/git/commits{/sha}","comments_url":"https://api.github.com/repos/TimothyGu/webidl/comments{/number}","issue_comment_url":"https://api.github.com/repos/TimothyGu/webidl/issues/comments{/number}","contents_url":"https://api.github.com/repos/TimothyGu/webidl/contents/{+path}","compare_url":"https://api.github.com/repos/TimothyGu/webidl/compare/{base}...{head}","merges_url":"https://api.github.com/repos/TimothyGu/webidl/merges","archive_url":"https://api.github.com/repos/TimothyGu/webidl/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/TimothyGu/webidl/downloads","issues_url":"https://api.github.com/repos/TimothyGu/webidl/issues{/number}","pulls_url":"https://api.github.com/repos/TimothyGu/webidl/pulls{/number}","milestones_url":"https://api.github.com/repos/TimothyGu/webidl/milestones{/number}","notifications_url":"https://api.github.com/repos/TimothyGu/webidl/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/TimothyGu/webidl/labels{/name}","releases_url":"https://api.github.com/repos/TimothyGu/webidl/releases{/id}","deployments_url":"https://api.github.com/repos/TimothyGu/webidl/deployments","created_at":"2017-08-06T23:40:56Z","updated_at":"2017-08-06T23:40:58Z","pushed_at":"2017-09-05T02:25:42Z","git_url":"git://github.com/TimothyGu/webidl.git","ssh_url":"git@github.com:TimothyGu/webidl.git","clone_url":"https://github.com/TimothyGu/webidl.git","svn_url":"https://github.com/TimothyGu/webidl","homepage":"https://heycam.github.io/webidl/","size":18111,"stargazers_count":0,"watchers_count":0,"language":"Shell","has_issues":false,"has_projects":true,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":0,"mirror_url":null,"open_issues_count":0,"forks":0,"open_issues":0,"watchers":0,"default_branch":"master"}},"base":{"label":"heycam:master","ref":"master","sha":"f869be829d37c03c8570807791321d6d16bbab84","user":{"login":"heycam","id":1484434,"avatar_url":"https://avatars2.githubusercontent.com/u/1484434?v=4","gravatar_id":"","url":"https://api.github.com/users/heycam","html_url":"https://github.com/heycam","followers_url":"https://api.github.com/users/heycam/followers","following_url":"https://api.github.com/users/heycam/following{/other_user}","gists_url":"https://api.github.com/users/heycam/gists{/gist_id}","starred_url":"https://api.github.com/users/heycam/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/heycam/subscriptions","organizations_url":"https://api.github.com/users/heycam/orgs","repos_url":"https://api.github.com/users/heycam/repos","events_url":"https://api.github.com/users/heycam/events{/privacy}","received_events_url":"https://api.github.com/users/heycam/received_events","type":"User","site_admin":false},"repo":{"id":14131914,"name":"webidl","full_name":"heycam/webidl","owner":{"login":"heycam","id":1484434,"avatar_url":"https://avatars2.githubusercontent.com/u/1484434?v=4","gravatar_id":"","url":"https://api.github.com/users/heycam","html_url":"https://github.com/heycam","followers_url":"https://api.github.com/users/heycam/followers","following_url":"https://api.github.com/users/heycam/following{/other_user}","gists_url":"https://api.github.com/users/heycam/gists{/gist_id}","starred_url":"https://api.github.com/users/heycam/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/heycam/subscriptions","organizations_url":"https://api.github.com/users/heycam/orgs","repos_url":"https://api.github.com/users/heycam/repos","events_url":"https://api.github.com/users/heycam/events{/privacy}","received_events_url":"https://api.github.com/users/heycam/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/heycam/webidl","description":"Web IDL","fork":false,"url":"https://api.github.com/repos/heycam/webidl","forks_url":"https://api.github.com/repos/heycam/webidl/forks","keys_url":"https://api.github.com/repos/heycam/webidl/keys{/key_id}","collaborators_url":"https://api.github.com/repos/heycam/webidl/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/heycam/webidl/teams","hooks_url":"https://api.github.com/repos/heycam/webidl/hooks","issue_events_url":"https://api.github.com/repos/heycam/webidl/issues/events{/number}","events_url":"https://api.github.com/repos/heycam/webidl/events","assignees_url":"https://api.github.com/repos/heycam/webidl/assignees{/user}","branches_url":"https://api.github.com/repos/heycam/webidl/branches{/branch}","tags_url":"https://api.github.com/repos/heycam/webidl/tags","blobs_url":"https://api.github.com/repos/heycam/webidl/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/heycam/webidl/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/heycam/webidl/git/refs{/sha}","trees_url":"https://api.github.com/repos/heycam/webidl/git/trees{/sha}","statuses_url":"https://api.github.com/repos/heycam/webidl/statuses/{sha}","languages_url":"https://api.github.com/repos/heycam/webidl/languages","stargazers_url":"https://api.github.com/repos/heycam/webidl/stargazers","contributors_url":"https://api.github.com/repos/heycam/webidl/contributors","subscribers_url":"https://api.github.com/repos/heycam/webidl/subscribers","subscription_url":"https://api.github.com/repos/heycam/webidl/subscription","commits_url":"https://api.github.com/repos/heycam/webidl/commits{/sha}","git_commits_url":"https://api.github.com/repos/heycam/webidl/git/commits{/sha}","comments_url":"https://api.github.com/repos/heycam/webidl/comments{/number}","issue_comment_url":"https://api.github.com/repos/heycam/webidl/issues/comments{/number}","contents_url":"https://api.github.com/repos/heycam/webidl/contents/{+path}","compare_url":"https://api.github.com/repos/heycam/webidl/compare/{base}...{head}","merges_url":"https://api.github.com/repos/heycam/webidl/merges","archive_url":"https://api.github.com/repos/heycam/webidl/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/heycam/webidl/downloads","issues_url":"https://api.github.com/repos/heycam/webidl/issues{/number}","pulls_url":"https://api.github.com/repos/heycam/webidl/pulls{/number}","milestones_url":"https://api.github.com/repos/heycam/webidl/milestones{/number}","notifications_url":"https://api.github.com/repos/heycam/webidl/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/heycam/webidl/labels{/name}","releases_url":"https://api.github.com/repos/heycam/webidl/releases{/id}","deployments_url":"https://api.github.com/repos/heycam/webidl/deployments","created_at":"2013-11-05T04:17:09Z","updated_at":"2017-08-14T14:06:50Z","pushed_at":"2017-09-05T02:25:44Z","git_url":"git://github.com/heycam/webidl.git","ssh_url":"git@github.com:heycam/webidl.git","clone_url":"https://github.com/heycam/webidl.git","svn_url":"https://github.com/heycam/webidl","homepage":"https://heycam.github.io/webidl/","size":18268,"stargazers_count":50,"watchers_count":50,"language":"Shell","has_issues":true,"has_projects":true,"has_downloads":true,"has_wiki":true,"has_pages":true,"forks_count":42,"mirror_url":null,"open_issues_count":92,"forks":42,"open_issues":92,"watchers":50,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/heycam/webidl/pulls/426"},"html":{"href":"https://github.com/heycam/webidl/pull/426"},"issue":{"href":"https://api.github.com/repos/heycam/webidl/issues/426"},"comments":{"href":"https://api.github.com/repos/heycam/webidl/issues/426/comments"},"review_comments":{"href":"https://api.github.com/repos/heycam/webidl/pulls/426/comments"},"review_comment":{"href":"https://api.github.com/repos/heycam/webidl/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/heycam/webidl/pulls/426/commits"},"statuses":{"href":"https://api.github.com/repos/heycam/webidl/statuses/53005fc0277db96110839d5c028253e635e52919"}},"author_association":"CONTRIBUTOR"}}
{"actor":{"display_login":"TimothyGu"}}