Question

我正在使用JsDoc3和Closure Compiler。我使用JsDoc template which outputs JSON为我用自定义脚本制作HTML。

我有一个返回自定义类的函数（但我没有，也不需要构造函数），我希望能够记录它（函数）以及返回对象中存在的函数。

myLib.defer = function() {

    return {
        'then':    function() {},
        'resolve': function() {},
        'reject':  function() {},
        'notify':  function() {},
        'promise': function() {}
    };

};

我如何记录这个？我没有构造函数，我也不需要。我对记录“类”并不在意（< strong>我不需要一个，此外，返回的对象记录在此函数的@return中， 我唯一需要的是记录那些函数存在于返回的对象 中，因此它们最终出现在JsDoc的JSON输出中以供我抓取。

另外，我正在使用Closure Compiler的AVANCED_OPTIMIZATIONS模式，因此如果有任何变通方法的副作用（例如无用的代码），那么这是一个很好的解决方法。

Answer 1

不幸的是，没有办法做到这一点看起来并不尴尬，但这很有效。

首先，可以将没有interface构造函数的类记录为Chad mentioned。它看起来像这样：

/**
 * Description of the Deferred interface.
 * @interface Deferred
 */
function Deferred() {}

可以像这样记录它的方法（例如）：

/**
 * Returns a Promise
 * @function Deferred.promise
 * @return {Promise} A Promise.
 */
Deferred.prototype.promise = function() {};

然后，在返回无构造函数的类的函数上，您可以像这样注释您的返回：

myLib.defer = function() {

    /** @type {Deferred} */
    return {
        'then':    function() {},
        'resolve': function() {},
        'reject':  function() {},
        'notify':  function() {},
        'promise': function() {}
    };

};

然而，这只会通过Closure Compiler;它不会被JsDoc3 JSON export template（也许是常规的）正确转换，所以我们需要@class annotation（CC忽略）：

/**
 * Description of the Deferred interface.
 * @interface Deferred
 * @class Deferred
 */
function Deferred() {}

完成所有这些后，我们的文档将正确生成，并且我们的代码将编译为与之前相同的内容 - 所有样板文件在编译时作为死代码被删除。

更新：正如Chad所提到的，如果您尝试直接实例化非接口，则不会收到警告，这可能不好，您可能不喜欢它（Interfaces 如果实例化将抛出错误。）

解决此问题的一种方法是将接口构造函数@private设置为@const对象字面值，如his answer至that question中所述。

Answer 2

重复的问题。请参阅How to document return in JavaScript。

在这种情况下，由于它看起来像一个库，您可能需要声明并使用一个接口。有关示例，请参阅jQuery externs。

如何记录函数（而不是构造函数）返回的类型及其方法

2 个答案: