JSDoc未解析类属性求助：为何m、rows、cols字段被忽略？

这个问题我之前也碰到过，本质是JSDoc对原型模式下构造函数内延迟赋值的实例属性的静态解析逻辑导致的。

具体原因 #

你当前的代码里，虽然在构造函数内给this.m、rows、cols加了注释，但只是先写了this.m;这种空声明，然后在if/else分支里才真正赋值。JSDoc在解析原型扩展的构造函数时，静态分析器可能没把这些空声明和后面的赋值关联起来，也就没识别到它们是Matrix的实例属性。

而当你不使用prototype（把方法都写在构造函数内部）时，构造函数内的属性注释和赋值是紧耦合的，JSDoc能直接识别这些属性属于实例。

解决办法 #

这里有几种靠谱的修正方式，任选一种都能让JSDoc正确识别这些属性：

方法1：用@property在构造函数的类注释里声明实例属性

直接在Matrix的构造函数JSDoc里用@property定义所有实例属性，这样最清晰：

/** 
 * Matrix object for operations on matrices 
 * @constructor
 * @param {number[][]} m - values
 * @param {number} def - default size def x def
 * @property {number[][]} m - Matrix values
 * @property {number} rows - Number of rows
 * @property {number} cols - Number of columns
 */
function Matrix(m, def){
  if(m != null){
    this.m = m;
    this.rows = m[0].length;
    this.cols = m.length;
  } else {
    this.m = new Array(def);
    for (var i = 0; i < def; i++) {
      this.m[i] = new Array(def);
    }
    this.rows = def;
    this.cols = def;
    this.initI();
  }
}

/**
 * initializes the Matrix as Ident-Matrix
 */
Matrix.prototype.initI = function(){
  for(var i = 0; i < this.rows; i++){
    for(var j = 0; j < this.cols; j++) {
      if(i == j) this.m[i][j] = 1;
      else this.m[i][j] = 0;
    }
  }
}

方法2：给属性注释添加@instance或@memberof

在构造函数内的属性注释里明确标注属于Matrix实例：

/** 
 * Matrix object for operations on matrices 
 * @constructor
 * @param {number[][]} m - values
 * @param {number} def - default size def x def
 */
function Matrix(m, def){
  /** 
   * Matrix values
   * @type {number[][]}
   * @instance
   */
  this.m;
  /** 
   * Number of rows
   * @type {number}
   * @instance
   */
  this.rows;
  /** 
   * Number of columns
   * @type {number}
   * @instance
   */
  this.cols;

  if(m != null){
    this.m = m;
    this.rows = m[0].length;
    this.cols = m.length;
  } else {
    this.m = new Array(def);
    for (var i = 0; i < def; i++) {
      this.m[i] = new Array(def);
    }
    this.rows = def;
    this.cols = def;
    this.initI();
  }
}

/**
 * initializes the Matrix as Ident-Matrix
 */
Matrix.prototype.initI = function(){
  for(var i = 0; i < this.rows; i++){
    for(var j = 0; j < this.cols; j++) {
      if(i == j) this.m[i][j] = 1;
      else this.m[i][j] = 0;
    }
  }
}

方法3：直接在赋值语句上添加注释

去掉空的this.m;声明，直接在赋值的时候加注释，让JSDoc直接关联赋值和类型：

/** 
 * Matrix object for operations on matrices 
 * @constructor
 * @param {number[][]} m - values
 * @param {number} def - default size def x def
 */
function Matrix(m, def){
  if(m != null){
    /** @type {number[][]} Matrix values */
    this.m = m;
    /** @type {number} Number of rows */
    this.rows = m[0].length;
    /** @type {number} Number of columns */
    this.cols = m.length;
  } else {
    /** @type {number[][]} Matrix values */
    this.m = new Array(def);
    for (var i = 0; i < def; i++) {
      this.m[i] = new Array(def);
    }
    /** @type {number} Number of rows */
    this.rows = def;
    /** @type {number} Number of columns */
    this.cols = def;
    this.initI();
  }
}

/**
 * initializes the Matrix as Ident-Matrix
 */
Matrix.prototype.initI = function(){
  for(var i = 0; i < this.rows; i++){
    for(var j = 0; j < this.cols; j++) {
      if(i == j) this.m[i][j] = 1;
      else this.m[i][j] = 0;
    }
  }
}

这几种方式都能让JSDoc正确识别你的实例属性，个人推荐第一种用@property的写法，结构更清晰，维护起来也方便。

内容的提问来源于stack exchange，提问作者user9648914