使用 Google Closure Compiler 记录回调参数答案

【问题标题】：Documenting callback parameters using Google Closure Compiler使用 Google Closure Compiler 记录回调参数
【发布时间】：2016-02-27 05:40:13
【问题描述】：

如何使用 Google Closure Compiler 记录回调参数的名称和描述？

阅读this answer on documenting callbacks with 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，在尝试使用回调名称作为类型时会给出警告“Unknown type EndDrawCallback”：

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

我能看到的唯一选择是

(a) 在回调参数之后放弃并编写文档而不使用标签，或者 (b) 重构代码以将单个对象传递给回调，并带有命名属性。

至少在这种情况下，(b) 不是一个选项。有没有办法做到这一点？如果有，怎么做？

【问题讨论】：

您只是想要 jsdoc 来生成文档吗？或者你想用它们进行闭包编译器类型检查？
类型检查将是一个额外的好处，但主要是我只想尽可能少地重复获取文档。这里重复的主要来源是function(string,boolean)，然后是@param {string} ...。将它放在两个不同的注释块中意味着它可能很容易出现分歧，因此最好定义一次回调类型然后引用它。

标签： javascript callback documentation google-closure-compiler jsdoc

【解决方案1】：

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

【讨论】：

这是摆脱警告的好建议，谢谢。