Re: [heycam/webidl] Describing overloaded methods (#241)

To be more specific about the issue:

When you define an IDL method, Bikeshed allows several different ways to refer to it to create an autolink.  If the method has no overloads, you can just refer to it by name without args, like `FormData/append()`. However, it also allows you to refer to it with arg-full signatures; you refer to the arguments by name, and any valid call signature (paying attention to optional args) is allowed, like `FormData/append(name, value)` or `FormData/append(name, value, filename)`.

This is a slight mismatch from IDL, which cares about argument *types*, not names, and distinguishes overloads by type. However, it matches how people naturally like to refer to things; it's not common to write something like `FormData/append(DOMString, DOMString)`.  It's also almost never an issue: if there's no overload, using name or type doesn't matter; if there are overloads with different argument names (which, I think, is the common case), then using names distinguishes the overloads just as effectively as types do.

The problem arises only when someone wants to define an overloaded method, and use the same arg names for more than one of the overloads. This is Anne's situation - he's trying to define "FormData.append(DOMString name, DOMString value)" *and* "FormData.append(DOMString name, Blob value, optional DOMString filename)". Because the signature `FormData/append(name, value)` could refer to either of these, Bikeshed ends up complaining that there's some ambiguity/duplication.

My suggested solution is to just change one of the argument names; that way each possible name-based signature only refers to a single unambiguous overload.  Anne's objecting that, since the two overloads are just alternate signatures for a single underlying function, he shouldn't need to do so.

-- 
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/241#issuecomment-261681214