Question

I am trying to understand the JSDoc style for documenting JavaScript that is used with the JavaScript Closure Compiler. I have the JavaScript code below

// ==ClosureCompiler==
// @compilation_level ADVANCED_OPTIMIZATIONS
// ==/ClosureCompiler==

(function(){
    /**
     * @type Array.<string>
     * @private
     */
    var sb = [];

    /**
     * @const
     * @type{{append: function(string): SingletonStringBuffer, toString: function(): string}}
     */
    window['SingletonStringBuffer'] = {
        /**
         * @param {string} text
         * @return {SingletonStringBuffer}
         */
        append: function(text){
            sb.push(text);
            return SingletonStringBuffer;
        },
        /**
         * @return {string}
         */
        toString: function(){
            return sb.join("");
        }
    };
}());

When I do an advanced compile on this code I am receiving 2 warnings.

JSC_TYPE_PARSE_ERROR: Bad type annotation. Unknown type SingletonStringBuffer at line 10 character 35
* @type{{append: function(string): SingletonStringBuffer, toString: function()...
                                   ^ JSC_TYPE_PARSE_ERROR: Bad type annotation. Unknown type SingletonStringBuffer at line 15 character 11
* @return {SingletonStringBuffer}
           ^

The function append returns a deference to the encapsulating object. The variable that it is returning ,SingletonStringBuffer, is declared… so I am not sure what is wrong or how to correct it.

Answer 1

You haven’t created a named type as far as the compiler is concerned. For this case, I would expect you to create an interface:

/** @interface */
function StringBuffer() {
}
/**
 * @param {string} text
 * @return {StringBuffer}
 */
StringBuffer.prototype.append;

etc

This can be declared either in the code (if you are using advanced mode it will be stripped) or in your extern files (if you want the type without the code in simple mode).

You can then use it like so (in your case):

(function(){
/**
 * @type Array.<string>
 * @private
 */
var sb = [];

/**
 * @const
 * @type {StringBuffer}
 */
window['SingltonStringBuffer'] = {
    /**
     * @param {string} text
     * @return {StringBuffer}
     */
    append: function(text){
        sb.push(text);
        return SingltonStringBuffer;
    },
    /**
     * @return {string}
     */
    toString: function(){
        return sb.join("");
    }
};
}());