只读的Ember计算属性应该在YUIdoc中标记为@property或@method吗?

Question

如何在YUIdoc中记录只读计算属性(例如Ember.js模型)?

假设我有一个简单模型:

/**
 * 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函数，它是一个只读属性。另一方面，它是从可编辑/可设置属性派生出来的，所以它可以随着用户操作的结果而改变。

还是@method ?因为它不仅使用了其他属性，还对它们进行了转换?变换部分在这样一个简单的例子中并不明显，但是假设一个计算属性是nameInitials，它只返回第一个&姓什么的?

也:我是否正确使用@property标签烬属性，而不是@attribute标签?

Answer 1

TL;DR:我认为你应该使用这个模板:

@property name
@type {type}
@public/@private

根据Gaurav的建议，如果您使用.readOnly()或computed.readOnly()，请添加@readOnly，如果@default有默认值(不是null或undefined)。

解释:

关于@method题:no, please no!从你的对象的消费者的角度来看(这就是你的API文档的基本用途)。你不能像调用方法那样调用object.property()。但是只要您使用Ember的getter和setter(您总是应该这样做)，CP的行为就完全像静态属性一样。它的值不是Ember.ComputedProperty实例，而是该实例返回的值。因此，无论它是CP还是静态属性，对用户来说都是完全透明的，而且应该始终如此，因此您可以随时将静态属性更改为计算属性，反之亦然，而不会破坏任何东西!

并尝试总是指定访问关键字，如@public或@private，因为这有助于定义和推理你的"东西"的公共API。只有公共属性/方法可以被消费者使用，比如你的组件，也只有那些应该服从单元或组件集成测试，而你保留自由随时改变你的私有的东西，只要公共API不改变。

请不要使用@final关键字。文档可能有一点误导，但是final在其他(经典的面向对象)语言中是一个非常常见的关键字，它表示您可能不会在子类中重写此属性/方法。因此，除非是这种情况，否则不要使用

Answer 2

我认为这里应该是这样的:

@property fullName
@type String
@final

你应该使用@final, @readonly标签只适用于attributes。

Answer 3

ember.js源代码使用的是@property，而不是@method。

示例:https://github.com/emberjs/ember.js/blob/ae6c9e82b91fd5b695907e7b76c998a128a157d0/packages/ember-views/lib/views/text_field.js L108