为 Singleton 的 Google Closure Compiler 评论 JavaScript

Question

我试图了解与JavaScript Closure Compiler 一起使用的JSDoc style for documenting 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

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

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

(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

单例在闭包中的工作方式不同。我没有看到它的显式注释，但是编译器（在高级模式下）对某些内置函数有一些了解 单例将通过 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);

就是这样。

PS 你得到了错误的注释，因为{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);