1

应该如何在 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标签用于 Ember 属性而不是@attribute标签是否正确？

4

3 回答 3

1

我认为这是您应该在这里拥有的：

@property fullName
@type String
@final

您应该使用@final,@readonly标签仅用于attributes.

于 2016-06-23T10:44:12.080 回答
1

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.

于 2016-10-28T10:54:17.120 回答
0

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

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

于 2015-09-24T20:08:56.143 回答