jsdoc 不信任 @param 声明

【问题标题】：jsdoc doesn't trust @param declarationsjsdoc 不信任 @param 声明
【发布时间】：2015-01-03 06:47:42
【问题描述】：

在如下代码上运行 jsdoc 时，@param 文档将被忽略。我认为这是因为我在 IIFE 中返回函数，但考虑到这在 JS 中的常见模式，我很难相信 jsdoc 无法处理它。

/** @namespace */
var util = {
    /**
     * Repeat <tt>str</tt> several times.
     * @param {google.maps.Marker} str The string to repeat.
     * @param {number} [times=1] How many times to repeat the string.
     * @returns {string}
     */
    repeat: (function() {

        var magicNumber = 1;

        return function(str, times) {
            if (times === undefined || times < magicNumber) {
                times = magicNumber;
            }
            return new Array(times+1).join(str);
        };

    }())
};

【问题讨论】：

标签： jsdoc

【解决方案1】：

显然，如果 jsdoc 认为文档项是一个函数，它只会包含 @param 和 @return 文档。您可以通过在文档注释中指定 @function 来强制执行此行为。

这样就成功了：

/** @namespace */
var util = {
    /**
     * Repeat <tt>str</tt> several times.
     * @function <---- ADDED THIS LINE
     * @param {google.maps.Marker} str The string to repeat.
     * @param {number} [times=1] How many times to repeat the string.
     * @returns {string}
     */
    repeat: (function() {

        var magicNumber = 1;

        return function(str, times) {
            if (times === undefined || times < magicNumber) {
                times = magicNumber;
            }
            return new Array(times+1).join(str);
        };

    }())
};

（如果你问我有点乏味。我希望 jsdoc 能够足够聪明地意识到它是一个函数，或者只是信任用户而不必在任何地方添加@function。）

【讨论】：