是否有支持參數移位和「多態性」的JavaScript文檔生成器？

Question

您的JavaScript庫越「神奇」，使用文檔生成器的可能性就越小。

是否有人知道文檔生成器允許使用參數移動/參數多態性來記錄函數？

function example(required, optional, callback) { 
    if(typeof optional === 'function' && typeof callback === 'undefined') { 
     callback = optional; 
     optional = 'DEFAULT VALUE'; 
    } 

    // do work here 
} 

這可以如下叫：

example(required, optional, function() { 
    // do work 
}); 

example(required, function() { 
    // do work 
}); 

任何建議表示讚賞，以「使用一個通用的註釋/文檔塊」除外。

這是相關的，但不是重複： Document generic type parameters in JSDOC

Answer 1

It looks like JSDoc supports overloading of functions與@name fun @name fun^2我認爲有以下傳達你的意圖明確

/** 
    @name example 
    @function 
    @param {string} required 
    @param {Function} callback 
*/ 
/** 
    @name example^2 
    @function 
    @param {string} required 
    @param {string} [optional='DEFAULT VALUE'] 
    @param {Function} callback 
*/ 
function example() { 
    if(typeof optional === 'function' && typeof callback === 'undefined') { 
     callback = optional; 
     optional = 'DEFAULT VALUE'; 
    } 

    // do work here 
} 

然而，在你的情況，我認爲這將是如果您只是將可選參數切換到最後，那麼最簡單，那麼您將不需要超載

/** 
* @param required 
* @param {Function} callback 
* @param {String} [optional='DEFAULT VALUE'] 
*/ 
function example(required, callback, optional) { 
    if (typeof optional === 'undefined') { 
     optional = 'DEFAULT VALUE'; 
    } 
    // do work here 
}