Как задокументировать мгновенный вызов + анонимную функцию?

Используя 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, и ему не нравится JSDoc рядом с return function () {. Я предполагаю, что должен быть правильный способ сделать это. Я думаю, что мой настоящий вопрос: "как мне заткнуть GCC?": p

Я немного осмотрелся, но не нашел точно такой ситуации. Я бы предположил, что это довольно распространенное явление.

2 3
javascript anonymous-function jsdoc

2 ответа:

Я не профессионал 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;
}());

Это может быть потому, что вы возвращаете анонимную функцию.

Надеюсь, что это помогает.

EDIT :

Я выяснил, что тег @alias может заключить сделку. Может быть, вы можете попробовать с кодом, который я отредактировал в фрагменте кода.

Подробнее

0

Edit: согласно вашему комментарию, вы можете заставить 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++;
    };
}
-2