有没有支持参数移位和“多态性”的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
});

任何建议都会受到欢迎，但请勿使用“使用通用注释/文档块”的建议。

这与以下内容有关，但并非重复： 在JSDOC中记录通用类型参数。

- Jeff

---

我更新了我的回答，但我无法真正测试它。也许JSDOC确实支持重载。 - Ruan Mendes

Answer 1

看起来JSDoc支持函数重载，使用@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
}

- Ruan Mendes

---

我还没有测试过这个，但是你提出了一个满足我的需求并且还有一个解决方法。这正是我在答案中寻找的。感谢你的探究精神。 - Jeff