javascript - 在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 语句生成的文档在使用 jsdoc-toolkit 构建时看起来像这样。基本上，您会得到一个很好的事件详细信息部分，该部分描述了何时触发事件以及将哪些参数传递给回调。这也适用于 JSDoc3，并产生具有相同信息的事件部分。

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