Синтаксис, используемый для документирования полей функционального параметра, который является объектом

Question

Мне было интересно, как правильно документировать аргумент (который является объектом) и все его свойства.

1. Если я правильно понял, квадратные скобки означают «необязательно», верно?
2. Является ли синтаксис, используемый для описания свойств объекта, действительным?
3. Свойство reqSettings.retryInterval - это номер, но мне не удалось найти способ включить его устройство. Есть ли способ указать, что это число в миллисекундах?

Код:

/** 
    * 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

Если я правильно понял квадратные скобки означают "по желанию", верно?

Вы правильно поняли.

Является ли синтаксис, используемый для описания свойств объекта, действительным?

jsdoc понимает ваш синтаксис, поэтому я бы назвал его «действительным».

Свойство reqSettings.retryInterval - это номер, но мне не удалось найти способ включить его устройство. Есть ли способ указать, что это число в миллисекундах?

jsdoc не имеет специальный способ отметить это. Вы должны отметить это в своей документации, как и вы: «Интервал для использования между попытками (ms)»