JsDoc、ES6 和 @param {Constructor}答案

【问题标题】：JsDoc, ES6 and @param {Constructor}JsDoc、ES6 和 @param {Constructor}
【发布时间】：2016-01-14 01:15:20
【问题描述】：

我正在尝试使用 JsDoc 来记录 es6 类。不敢相信不能将类作为参数传递（类类型，而不是实例类型）。

我一直在尝试，但无法让这个简单的代码工作，因此 JsDoc 不会向我抛出一些警告。

除非我为我的每个类创建一个@typedef，然后手动添加所有自己的和继承的成员，否则我无法让它工作。连mixin都做不了！

有没有人成功传递了构造函数/类参数？让 JsDoc 在静态上下文中，而不是在实例上下文中？

/**
 * @class A
 */
class A {

    /**
     * @static
     */
    static helloFromClassA(){
    }
}

/**
 * @class B
 * @extends A
 */
class B extends A{

    /**
     * @static
     */
    static helloFromClassB(){
    }
}

/**
 * Class as object
 * @param {A} ClassArgument
 */
function fn1(ClassArgument){
    ClassArgument.helloFromClassA(); // Unresolved function or method helloFromClassA
    // Does not work because ClassArgument is interpreted as an
    // instance of A, not A's constructor
}

/**
 * // Class as function
 * @param {Function} ClassArgument
 */
function fn2(ClassArgument){
    ClassArgument.helloFromClassA(); // Unresolved function or method helloFromClassA
    // Does not work because ClassArgument is interpreted as an
    // empty function, not A's constructor
}

/**
 * // Type definition
 * @typedef {Object} AClass
 * @property {Function} helloFromClassA
 * @property {Function} super
 */

/**
 * // Trying to mixin the AClass
 * @typedef {Object} BClass
 * @property {Function} helloFromClassB
 * @mixes {AClass}
 * @mixes {A}
 */

/**
 * // Adding manually all members
 * @typedef {Object} BClass2
 * @property {Function} helloFromClassB
 * @property {Function} helloFromClassA
 */

/**
 * @param {BClass} ClassArgument
 */
function fn3(ClassArgument){
    ClassArgument.helloFromClassA(); // Unresolved function or method helloFromClassA
    // Does not work because the BClass typedef does not take
    // into account the mixin from AClass, nor from A
    ClassArgument.helloFromClassB(); // No warming
}

/**
 * @param {BClass2} ClassArgument
 */
function fn4(ClassArgument){
    ClassArgument.helloFromClassA(); // No Warning
    ClassArgument.helloFromClassB(); // No warming
    // Works because we manually defined the typedef with all own
    // and inherited properties. It's a drag.
}


fn1(B);

fn2(B);

fn3(B);

fn4(B);

jsDoc 问题：https://github.com/jsdoc3/jsdoc/issues/1088

【问题讨论】：

您已将这些方法声明为 static - 在实例上调用它们会起作用，但 imo 对关键字的使用有点奇怪。
什么意思？ ES6 有 static 关键字，允许你在构造函数而不是原型上声明方法。这些是静态方法。而且我不是在尝试在实例上调用它们，而是在调用构造函数。这里的问题是 JsDoc 不允许您将参数声明为构造函数（类型），它只允许您将参数声明为实例。
我明白了。我错误地认为 val 是一个实例而不是对函数的引用
是的，我是这么想的，所以我更新了代码。

标签： javascript ecmascript-6 webstorm jsdoc

【解决方案1】：

我在 WebStorm 中多次遇到自动完成的相同问题。虽然目前在 jsdoc 中似乎没有直接的方式来说明参数是对构造函数（而不是实例）的引用，但 JetBrains 团队建议实现类似 @param {typeof Constructor}（其中typeof 来自 typescript) 或 @param {Constructor.}，它是闭包编译器团队的 suggested。您可以为以下问题投票，以解决您对 WebStorm 自动完成的主要关注 - https://youtrack.jetbrains.com/issue/WEB-17325

【讨论】：

【解决方案2】：

在 Visual Studio Code 中，您可以指定

@param {function(new:MyClass, SomeArgType, SecondArgType, etc...)}

我不确定该语法来自什么规范或还有谁支持它，但它对我有用。

【讨论】：

【解决方案3】：

typescript 和 google 闭包都支持 {typeof SomeClass} 将类引用为类型（不是类实例）。不幸的是 jsdoc 不支持该语法并且无法编译它 (https://github.com/jsdoc3/jsdoc/issues/1349)。

因为我想用 typescript 对我的 JavaScript 进行类型检查，并且还想生成文档，所以我制作了这个 jsdoc 插件来将 {typeof SomeClass} 之类的表达式转换为 {Class<SomeClass>}，所以我可以同时拥有这两个东西：https://github.com/cancerberoSgx/jsdoc-typeof-plugin

【讨论】：

WebStorm也理解，见youtrack.jetbrains.com/issue/WEB-10214