javascriptoopjsdocjsdoc3

Inheriting documentation in JSDoc


I am trying to write documentation for my JS project, and my code is object-oriented. Here is a sample code:

/**
 * @classdesc Represents a Layer.
 * @class
 * @param {object} satellite - The satellite object.
 * @param {string} date - The image date.
 * 
 * @property {Satellite} satellite - The associated satellite.
 * 
 */
function Layer(satellite, date){

    var self = this;
    self.satellite = satellite;

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


/**
 * @classdesc Class representing a Layer for SAR satellites.
 * @class
 * @augments Layer
 */
function SarLayer(satellite, date, img_layernumber, pre_post){
    Layer.call(this, satellite, date, img_layernumber, pre_post);
    var self = this;
    /**
     * Do nothing (not used for SAR imagery).
     * @function compute_wi
     * @memberOf SarLayer
     * @override
     * @instance
     * @param {ee.ImageCollection} rgb - RGB imagery.
     * @returns {ee.ImageCollection} RGB imagery
    */
    self.compute_wi = function(rgb){
        return rgb;
    };

}
SarLayer.prototype = Object.create(Layer.prototype);
SarLayer.prototype.constructor = SarLayer;

I have two issues:

  1. The properties (here the satellite member) are not inherited in the child class documentation, how can I make that happen without simply copy pasting the @property... line?
  2. Most of the compute_wi documentation is the same for the parent class and the child class. How can I inherit the parent class documentation? If I remove the child class documentation, it will inherit the parent class documentation but without indicating that the method is overriden in the child class. I have tried @inheritdoc \ @overridebut it doesn't work. Do you have any ideas?

Solution

  • I solved my problem using:

    /**
     1. @classdesc Represents a Layer.
     2. @class
     3. @param {object} satellite - The satellite object.
     4. @param {string} date - The image date.
     5. 
     */
    function Layer(satellite, date){
    
        var self = this;
    
        /** Satellite object */
        this.satellite = satellite;
    
        /**
         * Compute the water index from RGB imagery.
         * @param {ee.ImageCollection} rgb - RGB imagery.
        */
        this.compute_wi = function(rgb){
            var image = rgb.median();
            return image.normalizedDifference(self.satellite.ndwi_bands);
        };
    }
    
    /**
     * @classdesc Class representing a Layer for SAR satellites.
     * @class
     * @augments Layer
     */
    function SarLayer(satellite, date, img_layernumber, pre_post){
        Layer.call(this, satellite, date, img_layernumber, pre_post);
        var self = this;
    
        /** Do nothing (not used for SAR imagery). */
        this.compute_wi = function(rgb){
            return rgb;
        };
    
    }
    SarLayer.prototype = Object.create(Layer.prototype);
    SarLayer.prototype.constructor = SarLayer;
    

    So basically for:

    1. by removing the property, and adding documentation in front of my member. (I also had to put this instead of self).
    2. I just keep the param and returns lines and remove the rest, changing from self to this made it work directly. It will detect overriding by itself.