使用Google闭包编译器记录回调参数

Documenting callback parameters using Google Closure Compiler

本文关键字：回调 参数 记录 编译器 Google 闭包 使用      更新时间：2023-09-26

如何使用Google闭包编译器记录回调参数的名称和描述？

在阅读了这个关于用JSDoc记录回调的答案后，我尝试使用@callback、@typedef和@name标记，但每一个都遇到了问题。

对于@callback，Closure会发出"非法使用未知JSDoc标签"警告：

/**
 * @callback EndDrawCallback
 * @param {string} action - either "keep", "discard", or "cancel"
 * @param {boolean} saveChanges - whether to mark changes as saved
**/

对于@typedef，它给出了一个"与其他注释不兼容的类型注释"：

/**
 * @typedef {function(string,boolean)}
 * @param {string} action ...
 * @param {boolean} saveChanges ...
**/
var EndDrawCallback;

使用@name，当尝试将回调名称用作类型时，它会发出警告"未知类型EndDrawCallback"

/**
 * @name EndDrawCallback
 * @function
 * @param {string} action ...
 * @param {boolean} saveChanges ...
**/

我能看到的唯一替代方案是

（a） 放弃并在不使用标记的情况下在回调参数之后编写文档，或者（b） 以重新构造代码，将具有命名属性的单个对象传递到回调中。

至少在这种情况下，（b）不是一个选项。有办法做到这一点吗？如果是，如何？

使用--extra_annotation_name标志指定编译器无法识别的JSDoc标记。由于编译器识别并使用@typedef，因此需要使用@callback或@name注释。

相关文章：