Emberjs documentation pages

1

Hy,

I have written an Emberjs application and am going to write documentation for it now. I was looking at the documentation pages of ember nad they looked very nice to me. I was wondering if anyone knew how they generated these documentation pages. I see that they have jsDoc comments in the code, but with which tool did they generate html pages from this?

Thanks

2

I donā€™t know what they use but we use yuidoc. There is an ember-cli package and it works great.

3

Thanks, I tried yuidoc and it seems to be working pretty well. Just some configuration.

4

Yes, Iā€™ve found yuidoc does a great job too. One of the ā€˜tricksā€™ I adopted was to use the @readOnly flag to denote a computed property. Another one I used was to keep Models, Components, etc. distinct by using i.e. ā€œ@namespace Modelsā€.

Does anyone have any good tricks for keeping actions in a different space that ordinary component/controller methods ? EDIT: I opted to add ā€œACTIONS.ā€ to the start of method names but I still think there may be a better way

Also, I was having a hard time finding a good example open source project that is heavily documented with yuidoc. Can anyone point me to one ?

5

If your code is on github, then checkout

6

Well, the Ember API Docs are :wink:

Personally, I denote my actions as @event. It may not be 100% correct, but it works fine.

7

Hereā€™s an example of how I implement YUIDoc:

import Ember from 'ember';

/**
* The login controller shows the login form and sends authentication data to the session.
*
* @class login
* @namespace Controller
*/
export default Ember.Controller.extend({

  /**
  * The session service.
  *
  * @property session
  * @readOnly
  * @type Service
  */
  session: Ember.inject.service('session'),

  /**
  * The identification, usually an username or e-mailaddress.
  *
  * @property identification
  * @type String
  * @default null
  */
  identification: '',

  /**
  * The password.
  *
  * @property password
  * @type String
  * @default null
  */
  password: '',


  actions: {

    /**
    * The authenticate action sends the identification and password to the session.
    *
    * @event authenticate
    * @return undefined
    */
    authenticate() {
      this.get('session').authenticate('authenticator:jwt', this.getProperties('identification', 'password'));
    }

  }

});
1 Like