Syntax to use to document the fields of a function parameter which is an object

Question

I was wondering what is the proper way to document an argument (which is an object) and all of its properties.

1. If I understood correctly square brackets mean "optional", is that right?
2. Is the syntax I used to describe the object properties valid?
3. The reqSettings.retryInterval property is a number, but I was unable to find a way to include its unit. Is there a way to indicate that this number is in milliseconds?

The code:

  /** 
   * used as a facade for the 'callServer' function.
   * @param {object} reqSettings           - a settings object to provide 'callServer'.
   * @param {object} reqSettings.ajaxOpt   - an object containing standard jquery ajax settings.
   * @param {function} reqSettings.success - a success handler for 'fulfilled' promises.
   * @param {function} reqSettings.failure="failResponse" - a failure handler for 'rejected' promises.
   * @param {number} [reqSettings.retries=0] - maximum retries allowed per cycle  
   * @param {number} [reqSettings.retryInterval=1500] - interval to use between retries (ms)  
   * @param {number} [reqSettings.attempted=1] - a counter used to count total attempts  
   */
  function gateKeeper(reqSettings) {
    if ( !reqSettings.retries )       { reqSettings.retries = 0 }
    if ( !reqSettings.retryInterval ) { reqSettings.retryInterval = 1500 }  
    if ( !reqSettings.attempted )     { reqSettings.attempted = 1 }

    reqSettings.retries--

    if ( !reqSettings.success || !reqSettings.ajaxOpt.url ) {
      throw new TypeError("success handler or ajax url property is missing")
    }

    return callServer(reqSettings)
  }

Answer 1

If I understood correctly square brackets mean "optional", is that right?

You understood correctly.

Is the syntax I used to describe the object properties valid?

jsdoc understands your syntax so I would call it "valid".

The reqSettings.retryInterval property is a number, but I was unable to find a way to include its unit. Is there a way to indicate that this number is in milliseconds?

jsdoc has no special way to note this. You have to note it in your documentation like you did: "interval to use between retries (ms)"