javascript 你如何用混合参数类型记录 JSDoc？
声明：本页面是StackOverFlow热门问题的中英对照翻译，遵循CC BY-SA 4.0协议，如果您需要使用它，必须同样遵循CC BY-SA许可，注明原文地址和作者信息，同时你必须将它归于原作者（不是我）：StackOverFlow
原文地址: http://stackoverflow.com/questions/16771258/
Warning: these are provided under cc-by-sa 4.0 license. You are free to use/share it, But you must attribute it to the original authors (not me):
StackOverFlow
How do you document JSDoc with mixed parameter type?
提问by Oliver Watkins
How do I document a method in JavaScript using JSDocwhen the parameter type can be mixed?
当参数类型可以混合时，如何使用JSDoc在 JavaScript 中记录方法？
I have method on a Dialog object where I can show HTML or my own Viewable objects. The method JSDoc looks like this:
我有一个 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){
..
}
Because JS doesn't allow method overloading, I need to create these types of methods, where a parameter in a method can be two disparate types. Is there a way to document this in JSDoc, or can JSDoc only let you document a param with one type?
因为 JS 不允许方法重载，所以我需要创建这些类型的方法，其中方法中的参数可以是两种不同的类型。有没有办法在 JSDoc 中记录这个，或者 JSDoc 只能让你记录一个类型的参数？
Also how would you document a paramater of type {Title:String, Id:String}? That is, an object passed in that is not of a type. Quasi, a JSON object.
另外，您将如何记录类型的参数{Title:String, Id:String}？也就是说，传入的对象不是类型。准，一个 JSON 对象。
回答by flavian
You can use the |separator to specify multiple types in the method type signature:
您可以使用|分隔符在方法类型签名中指定多种类型：
/**
* Some method
* @param {Object|string|number} param The parameter.
* @returns {Object|string|number} The modified param.
*/
function doSomething(param) {
return etc..
};
回答by Philzen
Google Closure Compiler Docsrecommend the following form - which looks official as it is the same as found on usejsdoc.org:
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..
};
To cite the above linked closure compiler docs:
引用上面链接的闭包编译器文档：
Note the parentheses, which are required.
请注意括号，这是必需的。
