使用JSDoc文档记录jQuery参数类型的正确方式是什么？

Question

我正在尝试使用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) {};

我在 Stack Overflow 上也找到了一个类似的问题：
如何让 JSDoc 将我的参数标记为 jQuery 对象？

- Jean-Philippe Martin

---

正确的做法不是使用jQ对象进行SOAP调用，而是分离关注点。仅此而已。尽管如此，这还是一个有趣的问题。 - Benjamin Gruenbaum

好的，我会研究一下。你能否建议一个模式替代方法？ - Jean-Philippe Martin

关注点分离是一种原则而不是模式。在这种情况下的想法（它适用于更多的GUI）是您的表示逻辑和业务逻辑不应该混合在一起。一些常见的设计模式，如中介者、观察者和事件发射器，可以解决这个问题。一些解决这个问题的架构模式包括MVC、MVVM和MVP。 - Benjamin Gruenbaum

谢谢你的架构建议...好的，所以GUI不直接与数据交互，反之亦然。明白了。 - Jean-Philippe Martin

@Jean-PhilippeMartin，我也曾经为文档化遗留代码而努力，这些代码并非我编写的。 - Andy

Answer 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) {};

- Louis

Answer 2

我在 github/js3doc 上看到了以下内容：

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

or github/js3doc

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

- Jean-Philippe Martin