Thread:Manual talk:Coding conventions/JavaScript/Code documentation: Distinguishing between object being compatible to interface by convention (duck typing) vs. requiring instance working with instanceof/reply (3)

While  may (implementation-wise) not be a public constructor, I would most certainly consider it a class. In essence it is a private class in jQuery that various other classes inherit from by calling the private object constructor function for promises. And while that constructor is not exposed, the objects constructed from it are.

objects mixin all public properties of the internally constructed promise. And  returns the promise object as-is. JavaScript doesn't really have classes to begin with anyway, and as such it is up to a constructor to decide whether to construct objects plainly (inheriting only from Object), or with additional prototypes in the chain. In the case of jQuery's promises, they are plain objects.

Anyway, in jsduck documentation nothing implies that it has to pass  in execution context. It should however pass "instance of" conceptually (an object created by the class documented in jsduck under that name). The idea of " " doesn't make sense in that case because for all intends and purposes the object is and must in fact be an instance of.

If the function you're documenting is invoked with a promise created by  (or its callers such as ,  ,   etc.) then using   seems most appropriate within the conventions of how we use jsduck.

If the function takes a compatible promise created by another library, then I agree we could have an abstract class definition for  that could be used for cases where you aren't dealing with promises made by jQuery per se. Be careful though with assuming what is part of a "standard" promises. The specification is still in flux. It's easy to assume you need a simple promise and end up relying on jQuery-specific behaviour.