在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语句会生成documentation that looks like this。基本上，您将获得一个很好的“事件详细信息”部分，该部分描述了事件何时被触发以及哪些参数传递给回调。这也适用于JSDoc3，并导致事件部分具有相同的信息。

请注意documentation describing the @event tag并没有准确地描述它以这种方式使用，但它确实提供了所需的输出。至于JSDoc3，@event和@fires标签还没有文档，但@event确实提供了我正在寻找的输出。