How to document an Ember App?

Question

I'm using YUIdoc. Anything else ? Well could anyone tell me how to properly document a model, a controller, a mixin and a view in Ember ?

For example I'm trying to document this:

App.newModel = DS.Model.extend({
    someProperty: DS.attr('string')
});

App.myController = Ember.Controller.extend({
    someProperty: ...
});

App.myMixin = Ember.Mixin.create({
    someProperty: ...
});

EDIT I'm now using YUIdoc instead of jsdoc3

Answer 1

You're going to have a hard time using JSDoc for Ember applications because JSDoc parses code and not just comments. Ember uses their own class-like syntax, so JSDoc isn't going to be able to recognize a lot of the code. I personally use YUIDoc, which is what the Ember team uses. (YUIDoc also allows you to import other documentation to resolve external references, like DS.Model.) There are other alternatives though. This page does some comparison, and gives you a difference chart that shows you which tools parse comments rather than source code.

Also, I realize that I am not answering your specific question. But this should help answer the question of what alternatives are out there, which may eliminate your JSDoc question altogether.

Answer 2

I have found ember-style-guide useful to me. But with few changes:

1. After the @module statement I write full path to it beginning from the project name. It gives me opportunity to link to it. For example:

   /**
    * @module dashboard/models/node
    * @augments module:ember-data/system/model
    * @public
    */
   export default DS.Model.extend({
   
     /**
      * @type {module:dashboard/models/node}
      */
     parent: DS.belongsTo("node"),
   
     /**
      * @type {Array<module:dashboard/models/node>}
      */
     childs: DS.hasMany("node"),
   
     /**
      * @method
      * @return {module:dashboard/models/node}
      */
     getFirstChild() {
       // ...
     }
   
   });
   

2. After the @augments statement I write a full path to module from which the current module is extended. If the module extended from a third part module I write full path of that module (getting it from the import statement). I'm not sure that it's right way, because in the generated doc no links to these modules. I did not found a way to make a link to them. Honestly, I'm not sure that is possible because different projects may use different doc comments engines and there is no way to tie modules (classes) by names.