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

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编译器，它不喜欢在return function () {附近的JSDoc。我猜应该有正确的方法来解决这个问题。我的真正问题是：“我如何让GCC安静呢？” :p 我搜索了一下，但没有找到完全相同的情况。我想这种情况很常见。

- Halcyon

---

当您使用您提出的签名时，是否遇到了错误？ - Jeremy

是的，确切的错误信息是：[file].js:[line]: 警告 - 错误的函数注释位置。这个 JSDoc 没有附加到一个函数节点上。你是否缺少括号？ - Halcyon

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标签可以解决这个问题。也许你可以尝试使用我在代码片段中编辑的代码。

更多细节请查看此处。

- Ganbin

---

去掉直接返回并给函数命名，可以消除gcc警告。我不确定是否同意IIFE的jsDoc，它似乎暗示myfunc返回一个函数，但实际上并不是这样。 - Halcyon

关于i没有被初始化，不用担心，这只是一个虚假的实现。 - Halcyon

你是正确的，myFunc返回的不是一个函数，所以我们可以使用和add函数相同的返回值吗？ - Ganbin

我已经编辑了我的帖子。@alias标签可能会有所帮助。 - Ganbin

我不确定 @alias 和 @name 是否被 Closure 所识别。我认为通过在各个地方添加内联类型转换，可能可以让 Closure 做正确的事情，但我不确定什么是正确的方法。 - Jeremy

Answer 2

编辑：根据您的评论，您可以通过“消除警告”来让GCC保持安静。请参见此处：https://github.com/google/closure-compiler/wiki/Warnings#warnings-level-api

我的回答其余部分是关于文档化JavaScript，而不一定是JSDoc的内部。

我建议将（外部）匿名函数编写为下面的命名函数声明。该函数的文档应该是一个普通函数，返回类型为函数，指出它即将被详细说明。

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

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++;
    };
}

- Reed Spool

---

我不想完全禁用gcc。按照您的建议进行重写对我来说似乎不是一个好主意。gcc给出的警告是关于jsDoc环绕return function () {的，这似乎还没有解决。 - Halcyon

好的，谢谢你讲得清楚。我不是 JSDoc 的用户，所以无法提供更多帮助。祝你好运！ - Reed Spool