Re: APIs that overload numbers and strings

On 4/14/13 6:18 PM, Allen Wirfs-Brock wrote:
>> We'd still need to handle numeric values passed in somehow, since I
>> doubt consumers are consistently using the named constants....
>
> the ES normal would be to just ToString the parameter

Sure, that's what would happen in WebIDL if we just added corresponding 
string values to the enum.

> It might be nice to try to explicitly identify those boundaries rather than having every API function assume that it must be one.

We could try; lots of specs specify APIs that in fact assume that 
they're running in trusted code without being particularly explicit 
about it...  It would be a good thing to try to do, but tough.

> I don't think you can expect WebIDL to meaningfully be able to describe all the semantic subtleties that occur in these APIs.

Sure.  The question is what tools it should provide to make the common 
cases easy and not lead people into creating bad APIs.

> this is probably where I would fall back to recommending that all API specs include a demonstration implementation of its functions written in JS (at least of the parameter processing, it is probably ok for the semantic guts to be a stub).  If it is hard or complex in JS then it probably isn't a very good API design

That's an interesting thought.

Though note that jQuery, say, does some nontrivial argument processing 
that while not "hard" is not exactly intuitive...  For example 
the|options = jQuery.extend( {}, options );| pattern.

-Boris

Received on Monday, 15 April 2013 14:56:46 UTC