使用Google Closure编译器记录回调参数 [英] Documenting callback parameters using Google Closure Compiler

问题描述

如何使用Google Closure编译器记录回调参数的名称和说明？

How can you document names and descriptions of callback parameters using the Google Closure Compiler?

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

After reading this answer on documenting callbacks with JSDoc, I tried using @callback and @typedef and @name tags, but ran into issues with each one.

使用 @callback ，闭包给出非法使用未知的JSDoc标签警告：

With @callback, Closure gives an "illegal use of unknown JSDoc tag" warning:

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

使用 @typedef ，它会给出与其他注释不兼容的类型注释：

With @typedef, it gives a "type annotation incompatible with other annotations":

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

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

Using @name, it gives a warning "Unknown type EndDrawCallback" when trying to use the callback name as a type:

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

我只能看到的替代方法是

The only alternatives I can see are

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

(a) to give up and write documentation after the callback param without using tags, or (b) to restructure the code to pass a single object into the callback, with named properties.

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

In this case at least, (b) is not an option. Is there a way to do this? If so, how?

推荐答案

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

Use the --extra_annotation_name flag to specify JSDoc tags that the compiler does not recognize. Since the compiler recognizes and uses @typedef, you would need to utilize either the @callback or @name annotations.

这篇关于使用Google Closure编译器记录回调参数的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！