你如何用混合参数类型记录 JSDoc？答案

【问题标题】：How do you document JSDoc with mixed parameter type?你如何用混合参数类型记录 JSDoc？
【发布时间】：2013-05-22 04:43:44
【问题描述】：

当参数类型可以混合时，如何使用 JSDoc 在 JavaScript 中记录方法？

我有一个关于 Dialog 对象的方法，我可以在其中显示 HTML 或我自己的 Viewable 对象。方法 JSDoc 如下所示：

/**
 * Can pass in viewable object, or some HTML element
 *
 * @param viewable viewable {Viewable} or HTML element {HTMLElement} or String {string}
 * @param {Boolean} cancelable is cancellable
 * @param title string or data object of String and Id {Title:String, Id:String} for setting HTML id value
 * @param {Array} actions array of functions actions display buttons on the bottom connecting to the passed in functions
 * @param {String} size mode. Can be mini,small,medium,large,maxi. Or of type {width:number, height:number}
 * @param {Number} zindex starting z-order. Note: first level dialog = 10,11,12, second level dialog 13,14,15 etc.
 */
Dialog.showElement = function(viewable, cancelable, title, actions, mode, zindex){
..
}

因为 JS 不允许方法重载，所以我需要创建这些类型的方法，其中方法中的参数可以是两种不同的类型。有没有办法在 JSDoc 中记录这一点，或者 JSDoc 只能让你记录一个类型的参数？

另外，您将如何记录{Title:String, Id:String} 类型的参数？也就是说，传入的对象不是类型。准，一个 JSON 对象。

【问题讨论】：

这可能不是原始 JSDoc 规范的一部分（我不知道），但请查看这篇解释如何为 Google Closure 编译器注释 JS 的文章：developers.google.com/closure/compiler/docs/…。它还有一个“记录类型”的示例。

标签： javascript jsdoc

【解决方案1】：

您可以使用|分隔符在方法类型签名中指定多个类型：

/**
 * Some method
 * @param {Object|string|number} param The parameter.
 * @returns {Object|string|number} The modified param.
 */
function doSomething(param) {
    return etc..
};

【讨论】：

但是我的 {Title:String, Id:String} 事情呢。我只能将其记录为 {Object} 吗？
所以如果我有那个和一个字符串，我会像 @param {String|{title: String, id: Object}} param 一样记录它吗？
@OliverWatkins 对于对象，可以执行以下操作@param {object|string} obj@param {string} obj.a@param {string} obj.b
@flavian 你的例子有参考吗？到目前为止，我能找到的官方文档需要括号（请参阅下面的答案） - 因此我认为这个答案在形式上是错误的......

【解决方案2】：

Google Closure Compiler Docs 推荐以下表格 - 看起来很正式，因为它与 usejsdoc.org 上的相同：

/**
 * Some method
 * @param {(Object|string|number)} param The parameter.
 * @returns {(Object|undefined)} The modified param.
 */
function doSomething(param) {
    return etc..
};

引用上面链接的闭包编译器文档：

注意括号，这是必需的。

【讨论】：