javascript - 声明函数触发 Polymer 元素中的事件的正确方法是什么？

Question

鉴于以下极其简化的自定义 Polymer 元素，我应该如何记录由“add”函数触发的“added-numbers”事件，以便它出现在 iron-component 生成的文档页面中-page(下图)？

<dom-module id="my-element">
  <template>
    <style>
      :host { display: block; }
    </style>
  </template>
  <script>
    Polymer({
      is: 'my-element',
      properties: {
        // properties go here
      },
      /**
      * Just adds two numbers together and fires an event.
      * @param {Number} a The first number
      * @param {Number} b The second number
      * @fires my-element#added-numbers I WANT TO DOCUMENT THE EVENT HERE
      */
      add: function (a, b) {
        var c = a + b;
        this.fire('added-numbers', { value: c });
      }
    });
  </script>
</dom-module>

polymer 文档 itself展示了如何将事件作为函数来记录(带有摘要和参数)，但没有展示如何记录预期会触发事件(或多个事件)的函数的示例。

我查看了 JavaScript 文档的 JSDoc 标准，它有一个 @fires标签似乎是我所追求的(并且我已经尝试在上面使用它)，但是在生成文档页面时它被忽略了。

如果有任何不同，我正在使用 Polymer 版本 1.9。

Answer 1

使用@event 注释。只需在您的函数之前或元素内的任何其他位置添加一个新的注释 block

 /**
  * Just adds two numbers together and fires an event.
  * @param {Number} a The first number
  * @param {Number} b The second number
  */
  add: function (a, b) {
    var c = a + b;
    this.fire('added-numbers', { value: c });
  }

 /**
 * Fired when .....
 *
 * @event event-name
 * @param {{eventParam:boolean}} detail -
 *     eventParam: true if .....
 */