13

I was hoping that my code, something like below, could generate documents describing each property of the object literal with JSDoc(v2.4.0), but it did not work. Does anyone know how to work with JSDoc to generate documents from code that uses getter/setter?

/** Enum of days of week. */
var Day = {
    /** Sunday. */
    get Sun() { return 0; },
    /** Monday. */
    get Mon() { return 1; },
    /** Thuesday. */
    get Tue() { return 2; },
    /** Wednesday. */
    get Wed() { return 3; },
    /** Thursday. */
    get Thu() { return 4; },
    /** Friday. */
    get Fri() { return 5; },
    /** Saturday. */
    get Sat() { return 6; }
}
enobufs
  • 860
  • 1
  • 7
  • 12

2 Answers2

22

Use @type to document JavaScript get and set accessors. Something like the following should work with JSDoc:

    /**
     * Sunday.
     * @type {number}
     */
    get "Sun"() { return 0; },
    /**
     * Monday.
     * @type {number}
     */
    get "Mon"() { return 1; },

This documents each property as a member with a type of number.

jackvsworld
  • 1,453
  • 15
  • 17
  • Solves the overeager type warning, e.g. `Argument type {get: (function(): number)} is not assignable to parameter type number` – Bob Stein Jun 17 '20 at 14:03
1

You could use jQuery style getter / setter methods:

/**
 * Get colour of object
 * @returns {mixed}
 *//**
 * Set colour of object
 * @param {mixed} val
 * @returns {this}
 */
colour: function(val) {
    if (val === undefined)
       return this.colour;
    else {
       this.colour = val;
       return this;
    }
}

I have just been discussing this very issue with Michael himself. It is possible in jsDoc3 (https://github.com/micmath/jsdoc) due to a very cool feature. It is possible to stack multiple docblocks (one for getter and one for setter):

http://groups.google.com/group/jsdoc-users/browse_thread/thread/d4c7794bc8f6648e/94df7339e1fc4c91#94df7339e1fc4c91

Lea Hayes
  • 62,536
  • 16
  • 62
  • 111
  • 2
    The syntax demonstrated there is ES5 syntax, and it's perfectly standard now and not at all implementation-specific. As for get/set not being keywords, the proper way to look at them here is that they're *contextual* keywords. If the token following `get` is a colon, it's a data property. If the token following `get` is a name, it's an accessor property. (And the same for `set`, of course.) – Jeff Walden Dec 01 '11 at 08:49
  • @Jeff that's an interesting note. I have had a play and this syntax appears to work great in ie9, ff3.5, chrome15 and node but obviously not in older IE's. I have read about the ES5 `defineProperty` (which works in IE8+) but I have not come across the object literal syntax in the ES5 spec. I have updated my answer a little. – Lea Hayes Dec 01 '11 at 13:33
  • @Jeff as a side-question, do you know if it is possible to define a fall-in `Object.defineProperty` function that provides the most basic of getter/setter functionality in IE6-IE7? – Lea Hayes Dec 01 '11 at 13:40
  • @Jeff I have had a play and here is what I've come up with to support earlier versions of FF, Chrome but still stuck with IE9+ (http://jsfiddle.net/SZuyq/) – Lea Hayes Dec 01 '11 at 14:34
  • You can define one that provides "most" functionality, but it really depends how you define "most". `Object.defineProperty` also can change a property's configurability (whether it can be deleted, roughly) and its enumerability (whether it shows up in `for-in` loops). Neither of these (nor writability, for data properties) can be changed without `Object.defineProperty`. As a result I generally recommend people not half-implement `Object.defineProperty`, because it's unfortunately impossible to get the nuances right. – Jeff Walden Dec 02 '11 at 23:26
  • An interesting remark but this answer doesn't really answer the question. It could be useful as a comment at best. – mgol Oct 09 '12 at 13:06