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?
TL;DR: I think you should use this template:
@property name
@type {type}
@public/@private
As suggested by Gaurav add @readOnly if you use .readOnly() or computed.readOnly(), and @default if it has a default value (not null or undefined).
Explanation:
As for the @method question: no, please no! Look at it from the perspective of the consumer of your object (that's what your API docs are basically for). You cannot call object.property() as you would for a method. But as long as you use Ember's getters and setters (which you should always do), the CP behaves exactly as a static property. And the value of it is not the Ember.ComputedProperty instance, it is the value that this instance returns. So weather it is a CP or a static property is totally transparent to the consumer, and always should be, so you can change a static property to a computed one or vice versa at any time without breaking things!
And try to always specify the access keyword like @public or @private, as this helps to define and reason about the public API of your "thing". Only the public properties/methods may be used by the consumer of let`s say your component as well only those should be subject to unit or component integration tests, while you retain the freedom to always change your private stuff as long as the public API does not change.
And please, do not use the @final keyword. The docs might be a bit misleading there, but final is a pretty common keyword in other (classical object oriented) languages, that says that you may not override this property/method in a child class. So unless this is the case, don't use it.