只读 Ember 计算属性是否应该在 YUIdoc 中标记为 @属性 或 @method？
Should read-only Ember computed properties be marked as @property or @method in YUIdoc?
只读计算属性（例如，Ember.js 模型）应该如何在 YUIdoc 中记录为文档？
假设我有一个简单的模型：
/**
* 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')}`;
})
});
fullName应该标记为什么？
是@property吗？如果是这样，是否应该将其标记为 @readOnly？我可以从两个方面来看待它——因为它没有 setter 函数，所以它是只读的 属性。另一方面，它派生自 editable/settable 属性，因此它会随着用户操作而改变。
还是@method？因为它不仅使用了其他属性，而且实际上对它们进行了转换？在这样一个简单的例子中，转换部分并不那么明显，但是假设计算的 属性 类似于 nameInitials，它只返回名字和姓氏的第一个字母，等等？
另外：我对 Ember 属性使用 @property 标签而不是 @attribute 标签是否正确？
ember.js 源代码使用@属性，而不是@method。
我认为这是你应该在这里看到的：
@property fullName
@type String
@final
您应该使用 @final，@readonly 标签仅适用于 attributes。
TL;DR：我认为你应该使用这个模板：
@property name
@type {type}
@public/@private
按照 Gaurav 的建议，如果您使用 .readOnly() 或 computed.readOnly()，请添加 @readOnly，如果它具有默认值（不是 null 或undefined).
解释：
至于@method问题：不，请不要！从 object 的消费者的角度来看待它（这就是 API 文档的主要目的）。您不能像调用方法那样调用 object.property()。但是只要您使用 Ember 的 getter 和 setter（您应该始终这样做），CP 的行为就与静态 属性 完全一样。而且它的值不是Ember.ComputedProperty实例，而是这个实例returns的值。因此，无论是 CP 还是静态 属性 对消费者来说都是完全透明的，而且应该始终如此，因此您可以随时将静态 属性 更改为计算的，反之亦然，而不会破坏任何东西!
并尝试始终指定访问关键字，例如 @public 或 @private，因为这有助于定义和推理您的 [=44] 的 public API =].只有 public properties/methods 可以被让我们说你的组件的消费者使用，只有那些应该接受单元或组件集成测试，同时你保留随时更改你的私有内容的自由只要 public API 不变。
请不要使用@final关键字。那里的文档可能有点误导，但 final 在其他（classical object 导向）语言中是一个非常常见的关键字，也就是说你 可能不会 在 child class 中覆盖此 property/method。所以除非是这种情况，否则不要使用它。
只读计算属性（例如，Ember.js 模型）应该如何在 YUIdoc 中记录为文档？
假设我有一个简单的模型：
/**
* 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')}`;
})
});
fullName应该标记为什么？
是@property吗？如果是这样，是否应该将其标记为 @readOnly？我可以从两个方面来看待它——因为它没有 setter 函数，所以它是只读的 属性。另一方面，它派生自 editable/settable 属性，因此它会随着用户操作而改变。
还是@method？因为它不仅使用了其他属性，而且实际上对它们进行了转换？在这样一个简单的例子中，转换部分并不那么明显，但是假设计算的 属性 类似于 nameInitials，它只返回名字和姓氏的第一个字母，等等？
另外：我对 Ember 属性使用 @property 标签而不是 @attribute 标签是否正确？
ember.js 源代码使用@属性，而不是@method。
我认为这是你应该在这里看到的：
@property fullName
@type String
@final
您应该使用 @final，@readonly 标签仅适用于 attributes。
TL;DR：我认为你应该使用这个模板：
@property name
@type {type}
@public/@private
按照 Gaurav 的建议，如果您使用 .readOnly() 或 computed.readOnly()，请添加 @readOnly，如果它具有默认值（不是 null 或undefined).
解释：
至于@method问题：不，请不要！从 object 的消费者的角度来看待它（这就是 API 文档的主要目的）。您不能像调用方法那样调用 object.property()。但是只要您使用 Ember 的 getter 和 setter（您应该始终这样做），CP 的行为就与静态 属性 完全一样。而且它的值不是Ember.ComputedProperty实例，而是这个实例returns的值。因此，无论是 CP 还是静态 属性 对消费者来说都是完全透明的，而且应该始终如此，因此您可以随时将静态 属性 更改为计算的，反之亦然，而不会破坏任何东西!
并尝试始终指定访问关键字，例如 @public 或 @private，因为这有助于定义和推理您的 [=44] 的 public API =].只有 public properties/methods 可以被让我们说你的组件的消费者使用，只有那些应该接受单元或组件集成测试，同时你保留随时更改你的私有内容的自由只要 public API 不变。
请不要使用@final关键字。那里的文档可能有点误导，但 final 在其他（classical object 导向）语言中是一个非常常见的关键字，也就是说你 可能不会 在 child class 中覆盖此 property/method。所以除非是这种情况，否则不要使用它。