CODEWITHSUNDEEP
javascriptjsdoc
Joel
Joel

Reputation: 325

How can I document a variable required by a method with JSDoc?

Should I do something like this?

/**
* Constructor function
*
* @contructor
* @param {Number} x - a number.
*/
function foo(x){
    this.x = x;
    /**
     * Sum to x.
     * @param {Number} y - A number.
     * @param {Object} this - The bar.
     * @param {Number} this.x - A number [requered].
     */
    this.bar(y) {
        return this.x + y;
    }
}

Or in this case I shouldn't define in the comment the required definition of this.x.

Upvotes: 2

Views: 432

Answers (1)

user7637745
user7637745

Reputation: 985

When you document your code, you shouldn't disclose what are the internals of your methods to the "outside". Just document your methods properly and correctly what each method:

  • does
  • accepts (if any)
  • and returns (if any)

...in concise forms.

But if you want to document the internals of your objects, you can use the @private or @protected tags.

JSDoc tags as "accessibility modifiers"

More like this:

/**
 * Constructs foo, that does something useful.
 *
 * @contructor
 * @param {number} x - A number, which determines X.
 */
function foo(x){
    /*
     * An important number.
     *
     * @private
     * @type {number}
     */
    this._x = x;        

    /**
     * Returns the summary of X and Y.
     *
     * @param {number} y - A number to add to X.
     * @returns {number} The summary of X and Y.
     */
    this.bar(y){
        return this._x + y;
    }
}

This way, when you are using a type-checker or an IDE, you will be notified in case you've ignored a required argument.

JavaScript documentation options:

For typed JavaScript, check out:

Usage of JSDoc

Upvotes: 4

Related Questions