Documenting Ember apps with @constructor and @static

Question

Documentation tools like YUIDocs allow you to identify and describe Classes (object classes) using the @class tag in comment blocks. Each identified Class requires a @static or @constructor tag, defined as follows:

• @constructor - Indicates that the class is instantiable (created with the new keyword).
• @static - Indicates that you should not instantiate the class with new. You can call all of the class' methods statically.

In Ember, you often create subclasses using extend(). To the best of my knowledge, this does not create a new instance of a class. However, many of these definitions (e.g. a route's controller) are singleton even though you use extend() to define them.

Thus, my question is: in which common situations of documenting Classes in an ember app would you use @constructor vs @static? Such examples are:

• Initializers
• The Router
• Adapters
• Serializers
• Transformations
• Routes
• The Store
• Models
• Controllers
• Views
• Components
• Mixins

I don't include Handlebars helpers here because I believe they are actually methods, not classes, but if I'm wrong I will correct this question.

Answer 1

• Initializers - Method call on static instance inside of Ember.
• The Router - static instance (though technically it's created)
• Adapters - @constructor
• Serializers - @constructor
• Transformations - @constructor, assuming you're talking about DS.Transform
• Routes - @constructor
• The Store (this is Ember Data, they initialize an instance and hook it up inside the container)
• Models - @constructor if we're talking about DS.Model,
• Controllers - @constructor
• Adapters - @constructor
• Views - @constructor
• Components - @constructor
• Mixins - @constructorish, Ember.Mixin can be created, though the instances aren't. And you don't use extend to generated different types of mixins.

Routes are class definitions. You aren't creating a singleton when you use extend, you are just defining a class that Ember can use. If ember wants it, it will know by the naming schema, and it will attempt to create it using the class you've defined. The same pattern is used throughout Ember. Singleton is the default pattern with a few exceptions such as itemController or when you use render in your template, I'm sure there are a slew of others as well.