Làm cách nào để bạn tạo tài liệu JSDoc với kiểu tham số hỗn hợp?

Question

Làm cách nào để ghi lại một phương thức trong JavaScript bằng cách sử dụng JSDoc khi loại tham số có thể được trộn lẫn?

Tôi có phương pháp trên đối tượng Dialog nơi tôi có thể hiển thị HTML hoặc đối tượng có thể xem của riêng mình. Phương pháp JSDoc trông giống như sau:

/** 
* 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){ 
.. 
} 

Vì JS không cho phép quá tải phương thức, tôi cần tạo các kiểu phương thức này, trong đó một tham số trong một phương pháp có thể là hai loại khác nhau. Có cách nào để tài liệu này trong JSDoc, hoặc có thể JSDoc chỉ cho phép bạn tài liệu một param với một loại?

Ngoài ra, bạn sẽ ghi lại thông tin của người bán hàng loại {Title:String, Id:String} bằng cách nào? Đó là, một đối tượng được truyền vào đó không phải là một loại. Quasi, một đối tượng JSON.

Answer 1

Bạn có thể sử dụng | tách để xác định nhiều loại trong chữ ký loại phương pháp:

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

Answer 2

Google Closure Compiler Docs giới thiệu các hình thức sau đây - mà trông chính thức vì nó cũng giống như tìm thấy trên usejsdoc.org:

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

Để trích dẫn tài liệu trình biên dịch đóng được liên kết ở trên:

Lưu ý các dấu ngoặc đơn được yêu cầu.