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