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，它只返回第一个＆amp;的第一个字母。姓氏等？

另外：我是否更正使用Ember属性的@property标记，而不是@attribute标记？

Answer 1

我认为这就是你应该拥有的：

@property fullName
@type String
@final

您应该使用@final，@readonly标记仅适用于attributes。

Answer 2

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

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

根据Gaurav的建议，如果您使用@readOnly或.readOnly()则添加computed.readOnly()，如果@default具有默认值（null或{{undefined 1}}）。

<强>解释

关于@method问题：不，请不要！从您对象的消费者的角度来看（这是您的API文档基本上是什么）。您不能像调用方法一样调用object.property()。但只要您使用Ember的getter和setter（您应该总是这样做），CP就会像静态属性一样运行。并且它的值不是Ember.ComputedProperty实例，它是此实例返回的值。所以天气它是一个CP或静态属性对消费者是完全透明的，并且应该是，所以你可以随时将静态属性更改为计算属性，反之亦然，而不会破坏事物！

并尝试始终指定访问关键字，如@public或@private，因为这有助于定义和推理您的＆＃34;事物＆＃34;的公共API。只有公共属性/方法可以被消费者使用，比如说你的组件也只有那些应该接受单元或组件集成测试，而你只要公共API就可以自由地改变你的私有东西。不会改变。

并且请不使用@final关键字。这些文档可能会有点误导，但final在其他（经典的面向对象）语言中是一个非常常见的关键字，它表示你可能不会覆盖孩子的这个属性/方法类。所以，除非是这种情况，否则不要使用它。

Answer 3

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

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

在YUIdoc中，只读Ember计算属性是否应标记为@property或@method？

3 个答案: