I started working with the awesome JSDuck to document my projects (do you like the doc system on Sencha Touch?) and, since I’m a great fan of Deferred object, I saw the lack of support for this kind of pattern.
Setting the @return tag with something like @return {jQuery.Deferred} is not enough since the returned value that matters is that passed through the .resolve() method of the deferred object.

Would be nice to mark a method as “deferred” and use the @return tag to document the value passed with .resolve(), keeping in mind that the actual value returned by the function is a just e promise.

Luckly JsDuck supports custom tags:

require "jsduck/meta_tag"
module JsDuck::Tag
  # Implementation of @deferred tag
    class Deferred < JsDuck::MetaTag
    def initialize
      @name = "deferred"
      @key = :deferred
      @signature = {:long => "deferred", :short => "DEF"}
      @boolean = true
    end
  end
end

Put this somewhere, for example ‘jsduck/deferred.rb’ and remember to call JsDuck with the param “–meta-tags=jsduck/deferred.rb”.