While jQuery.Promise
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.
jQuery.Deferred
objects mixin all public properties of the internally constructed promise. And deferred.promise()
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 instanceof
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 jQuery.Promise
.
If the function you're documenting is invoked with a promise created by jQuery.Deferred
(or its callers such as $.ready
, jqXHR
, jQuery.fn.promise
etc.) then using jQuery.Promise
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 Promise
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.