Question

使用JSDoc，如何记录此代码？

var mynamespace = {};

/**
 * What do I put here?
 */
mynamespace.myfunc = (function () {
    var i = 0;
    /**
     * Do I need to put anything here?
     */
    return function (a) {
        return a + i++;
    };
}());

这种情况下的签名可能是：

/**
 * @param {Number} base
 * @return {Number}
 */

我使用的是Google Closure Compiler，它不像return function () {附近的JSDoc。我猜测必须有一个正确的方法来做到这一点。我想我真正的问题是：＆＃34;我如何关闭GCC？＆＃34; ：P

我环顾四周但是我并没有完全找到这种情况。我认为这很常见。

Answer 1

我不是JSDoc专家，但我可以建议你

首先，我建议将i变量初始化为0，以使函数不返回NaN值。但这只是代码的细节，与您根据JSDoc评论的问题无关。

也许您应该以这种方式组织代码以“关闭”GCC：

var mynamespace = {};

/**
 * Display the value we pass with a counter incremented each time we call the method
 * @name myFunc
 * @params {Number} a - value to add to the counter
 * @return {Number} addition of a and i++
 */
mynamespace.myfunc = (function () {
    var i;
    /**
     * @alias myFunc
     */
    function add(a) {
        return a + i++; 
    };
    return add;
}());

可能是因为你返回了一个匿名函数。

希望它有所帮助。

编辑：

我发现@alias标签可以达成交易。也许您可以尝试使用我在代码片段中编辑的代码。

More details

Answer 2

编辑：根据您的评论，您可以通过“静音警告”让GCC闭嘴。见这里：https://github.com/google/closure-compiler/wiki/Warnings#warnings-level-api

我的其余部分是关于记录JavaScript，而不一定是JSDoc的内部。

我建议将（外部）匿名函数编写为下面的命名函数声明。这个函数的文档应该是一个普通的函数，带有一个返回类型的函数，并指出它将在瞬间被阐述。

将namespaced属性分配给调用该函数的结果。在这里记录您的新命名空间函数，就像普通函数一样。

IIFE是JS力量的伟大示范，但为了可读性......呃。 IIFE最终是不必要的（我对这个说法有95％的感觉，很想看到一个反例）。

var mynamespace = {};

/**
 * A brand new safe, private, lovely closure
 * 
 * @param {Number} 
 * @return {Number} Will always be NaN since i was never defined? ;)
 */  
mynamespace.myfunc = factory();

/**
 * Factory for safe, private, lovely closure
 *
 * @return {Function} A fresh closure
 */    
function factory() {
    var i;

    // Return new closure (see signature above)
    return function (a) {
        return a + i++;
    };
}

如何记录立即调用+匿名函数？

2 个答案: