google-closure-compilergoogle-closurejsdoccode-documentation

How to document a string type in jsdoc with limited possible values


I am having a function that accepts one string parameter. This parameter can have only one of a few defined possible values. What is the best way to document the same? Should shapeType be defined as enum or TypeDef or something else?

Shape.prototype.create = function (shapeType) {
    // shapeType can be "rect", "circle" or "ellipse"...
    this.type = shapeType;
};

Shape.prototype.getType = function (shapeType) {
    // shapeType can be "rect", "circle" or "ellipse"...
    return this.type;
};

The second part of the problem is that the possible values of shapeType is not known in the file that defines shapeType as whatever you suggest. There are multiple files contributed by several developers who might add to the possible values of shapeType.

PS: Am using jsdoc3


Solution

  • How about declaring a dummy enum:

    /**
     * Enum string values.
     * @enum {string}
     */
    Enumeration = {
        ONE: "The number one",
        TWO: "A second number"
    };
    
    /**
     * Sample.
     * @param {Enumeration} a one of the enumeration values.
     */
    Bar.prototype.sample = function(a) {};
    
    
    b = new Bar();
    
    bar.sample(Enumeration.ONE)
    

    You need to at least declare the enum to JSDOC, for this, though. But the code is clean and you get auto-completion in WebStorm.

    The multiple files problem though cannot be solved this way.