JSDoc中类属性与方法文档继承的技术问题咨询

1. 子类继承父类属性文档的解决方案 #

父类的satellite是构造函数内定义的实例属性，无需复制粘贴文档，可在子类的类注释中通过@inheritDoc复用父类属性的文档内容：

修改后的SarLayer类注释：

/**
 * @classdesc Class representing a Layer for SAR satellites.
 * @class
 * @augments Layer
 * @property {Satellite} satellite - {@inheritDoc Layer#satellite}
 */

通过{@inheritDoc Layer#satellite}明确指定继承父类的属性文档，JSDoc会自动拉取对应描述，避免重复编写。

2. 重写方法继承文档并标记@override的解决方案 #

针对构造函数内定义的实例方法，需调整@override和@inheritDoc的写法，确保JSDoc正确识别继承与重写关系：

修改后的SarLayer内compute_wi方法注释：

/**
 * @override
 * @inheritDoc Layer#compute_wi
 * @function compute_wi
 * @memberOf SarLayer
 * @instance
 * @returns {ee.ImageCollection} RGB imagery (unchanged for SAR)
 */

这样既复用了父类方法的参数、基础描述等内容，又标记了方法已重写，同时可补充子类特有的返回说明。

如果想让JSDoc的继承逻辑更稳定，建议将方法定义在原型上（符合JS面向对象标准写法）：

父类Layer调整为原型方法： #

function Layer(satellite, date){
    this.satellite = satellite;
}

/**
 * Compute the water index from RGB imagery.
 * @function compute_wi
 * @memberOf Layer.prototype
 * @instance
 * @param {ee.ImageCollection} rgb - RGB imagery.
*/
Layer.prototype.compute_wi = function(rgb){
    var image = rgb.median();
    return image.normalizedDifference(this.satellite.ndwi_bands);
};

子类SarLayer调整为原型方法： #

function SarLayer(satellite, date, img_layernumber, pre_post){
    Layer.call(this, satellite, date, img_layernumber, pre_post);
}
SarLayer.prototype = Object.create(Layer.prototype);
SarLayer.prototype.constructor = SarLayer;

/**
 * @override
 * @inheritDoc Layer#compute_wi
 * @function compute_wi
 * @memberOf SarLayer.prototype
 * @instance
 * @returns {ee.ImageCollection} RGB imagery (unchanged for SAR)
*/
SarLayer.prototype.compute_wi = function(rgb){
    return rgb;
};

原型式定义能让JSDoc更准确识别继承关系，@override与@inheritDoc的组合效果更稳定。

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