jeudi 24 septembre 2015

Should read-only Ember computed properties be marked as @property or @method in YUIdoc?

How should read-only computed properties (say, of Ember.js Models) be documented as, in YUIdoc?

Say I have a simple model:

/**
 * Person model
 * @class Person
 * @extends Ember.Object
 * @constructor
 */
Person = Ember.Object.extend({
  /**
   * @property firstName
   * @type String
   */
  firstName: null,

  /**
   * @property lastName
   * @type String
   */
  lastName: null,

  /**
   * ? what goes here?
   */
  fullName: Ember.computed('firstName', 'lastName', function() {
    return `${this.get('firstName')} ${this.get('lastName')}`;
  })
});

What should fullName be marked as?

Is it a @property? And if so, should it be marked as @readOnly? I can see it both ways -- since it doesn't have a setter function, it's a read-only property. On the other hand, it's derived from editable/settable properties, so it can change as a result of user actions.

Or is it a @method? Because it not only uses other properties, but actually transforms them? The transforms part isn't as obvious in such a simple example, but say a computed property was something like nameInitials, which only returned the first letters of the first & last name, etc?

Also: Am I correct to use the @property tag for Ember properties, and not the @attribute tag?




Aucun commentaire:

Enregistrer un commentaire