Commenting JavaScript for Google Closure Compiler for Single

Question

我试图理解JSDoc风格，用于记录与JavaScript闭包编译器一起使用的JavaScript。 我有下面的JavaScript代码

// ==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("");
        }
    };
}());

当我对此代码进行高级编译时，我收到 2 个警告。

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}
           ^

函数 append 返回对封装对象的尊重。 它返回的变量 SingletonStringBuffer 被声明...所以我不确定出了什么问题或如何纠正它。

Answer 1

就编译器而言，您尚未创建命名类型。 对于这种情况，我希望您创建一个接口：

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

这可以在代码中声明（如果您使用的是高级模式，它将被剥离）或在您的 extern 文件中声明（如果您希望在简单模式下没有代码的类型）。

然后，您可以像这样使用它（在您的情况下）：

(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("");
    }
};
}());

Answer 2

单例在闭包中的工作方式不同。我还没有看到它的显式注释，但是编译器（在高级模式下）对某些内置函数有一些了解Singleton 将通过 goog.addSingletonGetter 函数声明，这是一个代码示例

/**                                                                                 
 * @constructor                                                                     
 * @extends {path.to.BaseClass}                                                 
 */
path.to.MyClass = function() {
  goog.base(this);
};
goog.inherits(path.to.MyClass, path.to.BaseClass);
goog.addSingletonGetter(path.to.MyClass);

就是这样。

附言您得到的注释不正确{SingltonStringBuffer}因为它从未声明为类。

.PPS。有些人在发布事实时漫无边际。我怀疑（但这未经测试）将构造函数设为私有可能会起作用。请注意示例中的尾随下划线

/**
 * @private -> NOTE THIS IS IN NO WAY VERIFIED                                                                                
 * @constructor                                                                     
 * @extends {path.to.BaseClass}                                                 
 */
path.to.MyClass_ = function() {
  goog.base(this);
};
goog.inherits(path.to.MyClass, path.to.BaseClass);
goog.addSingletonGetter(path.to.MyClass);