在 javascript 中记录传递给回调的参数的约定是什么？

Question

当使用 javadoc 风格的文档风格时，是否有记录传递给回调函数的参数的约定？

/**
 * @param cb {Function} A callback that will be passed a name (String) and a Number
/

Answer 1

这与事件比回调更相关，但我想发布它，因为它可能会在相关情况下为您提供帮助。如果您还在调用回调时触发事件，则可以使用此方法来记录该事件，然后在回调文档中，请注意它接收与事件相同的参数，并使用 @link 链接到该事件。

我使用如下所示的内容来记录F.js中的事件。它没有连接到任何特定代码，我将其转储到定义 F.Component 的脚本底部：

/**
 * Triggered when this component is shown
 *
 * @name F.Component#component:shown
 * @event
 *
 * @param {Object}  evt                 Event object
 * @param {String}  evt.name            This component's name
 * @param {F.Component} evt.component   This component
 */

当使用 jsdoc-toolkit 构建时，上面的 JSDoc 语句会生成如下所示的文档。基本上，您会得到一个很好的“事件详细信息”部分，其中描述了事件何时触发以及传递给回调的参数。这也适用于 JSDoc3，并生成具有相同信息的事件部分。

请注意，描述 @event 标记的文档并未准确描述以这种方式使用它，但它确实提供了所需的输出。就 JSDoc3 而言，@event和@fires标签还没有文档，但 @event 确实给出了我正在寻找的输出。