用 JSDoc 记录 jQuery 参数类型的正确方法是什么？答案

【问题标题】：What's the correct way to document a jQuery parameter type with JSDoc?用 JSDoc 记录 jQuery 参数类型的正确方法是什么？
【发布时间】：2013-12-13 16:12:23
【问题描述】：

我正在尝试使用 JSDoc 语法为我自己和需要查看我的代码的人们记录我的程序。我也在努力提高我的技能。

对于一个jQuery类型的参数，我有点疑惑。我知道这是一个对象，但它在我的程序中相当普遍，所以我认为我应该首先为 jQuery 类型声明一个 typedef，然后将其用作我的参数类型。所以我问，这是正确的做法吗？

/**
 * DOM object referenced by jQuery
 * @typedef {jQuery} $jQueryDomObject
 */

/**
* SOAP call that does ...
*
* @param {string} code Some desc ...
* @param {callback} fnctVa Some desc ...
* @param {$jQueryDomObject} $attrib Input field that ...
*/
myfunction = function (code, fnctVa, $attrib) {};

我也在 SO 这个问题上找到了，有点类似：
How can I get JSDoc to mark my param as a jQuery object?

【问题讨论】：

正确的做法是不使用 jQ 对象进行 SOAP 调用并分离关注点。只是说。不过这个问题很有趣。
好的，我会调查的。你会建议一种模式吗？
关注点分离是一种原则，而不是一种模式。这种情况下的想法（它不仅适用于 GUI）是您的表示逻辑和业务逻辑不应该像那样混合。解决该问题的一些常见设计模式是调解器、观察者和事件发射器。一些解决该问题的架构模式是 MVC、MVVM 和 MVP。
感谢架构提示...好的，因此 GUI 不会直接与数据对话，反之亦然。明白了。
@Jean-PhilippeMartin，我已经完成了很多相同的记录遗留代码的工作，但我没有亲自编写过。

标签： javascript jquery jsdoc

【解决方案1】：

对于一个 jQuery 对象的参数，我经常这样做：

@param {jQuery} foo

并且不要进一步定义 jQuery 是什么。这是众所周知的。但是，如果您愿意，您可以使用 jsdoc 3 执行此操作：

/**
 * jQuery object
 * @external jQuery
 * @see {@link http://api.jquery.com/jQuery/}
 */

/**
 * SOAP call that does ...
 *
 * @param {string} code Some desc ...
 * @param {callback} fnctVa Some desc ...
 * @param {external:jQuery} $attrib Input field that ...
 */
var myfunction = function (code, fnctVa, $attrib) {};

【讨论】：

【解决方案2】：

我也在github/js3doc上看到：

@param {jQuery object} obj The jQuery object you're looking for.

或github/js3doc

@param {module:jquery} jquery Some desc...

【讨论】：