Як описати аргументи «об’єкта» у jsdoc?

// My function does X and Y.
// @params {object} parameters An object containing the parameters
// @params {function} callback The callback function
function(parameters, callback) {
}

Але як я можу описати, як має бути структурований об'єкт параметрів? Наприклад, це має бути щось на кшталт:

{
  setting1 : 123, // (required, integer)
  setting2 : 'asdf' // (optional, string)
}

На сторінці вікі @param :

Параметри із властивостями

Якщо очікується, що параметр має певне властивість, ви можете документувати це відразу після тегу @param для цього параметра, наприклад:

 /**
  * @param userInfo Information about the user.
  * @param userInfo.name The name of the user.
  * @param userInfo.email The email of the user.
  */
 function logIn(userInfo) {
        doLogIn(userInfo.name, userInfo.email);
 }

Раніше був тег @config, який одразу слідував за відповідним @param, але, здається, був застарілим ( наприклад, тут ).

На сьогоднішній день існує 4 різних способи документування об'єктів як параметрів / типів. У кожного є своє використання. Тільки 3 з них можна використовувати для документування повернених значень.

Для об'єктів з відомим набором властивостей (Варіант А)

/**
 * @param {{a: number, b: string, c}} myObj description
 */

Цей синтаксис ідеально підходить для об'єктів, які використовуються лише як параметри для цієї функції та не потребують подальшого опису кожного властивості. Він може бути використаний для @returnsа .

Для об'єктів з відомим набором властивостей (Варіант В)

Дуже корисними є параметри з синтаксисом властивостей :

/**
 * @param {Object} myObj description
 * @param {number} myObj.a description
 * @param {string} myObj.b description
 * @param {} myObj.c description
 */

Цей синтаксис ідеально підходить для об'єктів, які використовуються лише як параметри для цієї функції та потребують подальшого опису кожної властивості. Це не можна використовувати для @returns.

Для об'єктів, які будуть використовуватися в більш ніж одній точці джерела

У цьому випадку дуже зручним є @typedef . Ви можете визначити тип в одній точці джерела і використовувати його в якості типу для @paramабо @returnsабо інших тегів JSDoc , які можуть зробити використання типу.

/**
 * @typedef {Object} Person
 * @property {string} name how the person is called
 * @property {number} age how many years the person lived
 */

Потім ви можете використовувати це в @paramтезі:

/**
 * @param {Person} p - Description of p
 */

Або в @returns:

/**
 * @returns {Person} Description
 */

Для об’єктів, значення яких всі однотипні

/**
 * @param {Object.<string, number>} dict
 */

Перший тип (рядок) документує тип ключів, які в JavaScript завжди є рядком або принаймні завжди будуть примусові до рядка. Другий тип (число) - тип значення; це може бути будь-який тип. Цей синтаксис можна використовувати і для @returns.

Ресурси

Корисну інформацію про типи документування можна знайти тут:

https://jsdoc.app/tags-type.html

PS:

для документування необов'язкового значення можна використовувати []:

/**
 * @param {number} [opt_number] this number is optional
 */

або:

/**
 * @param {number|undefined} opt_number this number is optional
 */

Я бачу, що відповідь про тег @return вже є, але я хочу дати докладнішу інформацію про нього.

Перш за все, офіційна документація JSDoc 3 не дає нам прикладів про @return для користувацького об'єкта. Перегляньте https://jsdoc.app/tags-returns.html . Тепер давайте подивимося, що ми можемо зробити, поки не з’явиться якийсь стандарт.

• Функція повертає об'єкт, де динамічно генеруються ключі. Приклад: {1: 'Pete', 2: 'Mary', 3: 'John'}. Зазвичай ми повторюємо цей об’єкт за допомогою for(var key in obj){...}.

  Можливий JSDoc відповідно до https://google.github.io/styleguide/javascriptguide.xml#JsTypes

  /**
   * @return {Object.<number, string>}
   */
  function getTmpObject() {
      var result = {}
      for (var i = 10; i >= 0; i--) {
          result[i * 3] = 'someValue' + i;
      }
      return result
  }

• Функція повертає об'єкт, де ключі відомі константи. Приклад: {id: 1, title: 'Hello world', type: 'LEARN', children: {...}}. Ми можемо легко отримати доступ до властивостей цього об'єкта: object.id.

  Можливий JSDoc відповідно до https://groups.google.com/forum/#!topic/jsdoc-users/TMvUedK9tC4

  • Прикидатися.

    /**
     * Generate a point.
     *
     * @returns {Object} point - The point generated by the factory.
     * @returns {number} point.x - The x coordinate.
     * @returns {number} point.y - The y coordinate.
     */
    var pointFactory = function (x, y) {
        return {
            x:x,
            y:y
        }
    }

  • Повний Монти.

    /**
     @class generatedPoint
     @private
     @type {Object}
     @property {number} x The x coordinate.
     @property {number} y The y coordinate.
     */
    function generatedPoint(x, y) {
        return {
            x:x,
            y:y
        };
    }
    
    /**
     * Generate a point.
     *
     * @returns {generatedPoint} The point generated by the factory.
     */
    
    var pointFactory = function (x, y) {
        return new generatedPoint(x, y);
    }

  • Визначте тип.

    /**
     @typedef generatedPoint
     @type {Object}
     @property {number} x The x coordinate.
     @property {number} y The y coordinate.
     */
    
    
    /**
     * Generate a point.
     *
     * @returns {generatedPoint} The point generated by the factory.
     */
    
    var pointFactory = function (x, y) {
        return {
            x:x,
            y:y
        }
    }

  Відповідно до https://google.github.io/styleguide/javascriptguide.xml#JsTypes

  • Тип запису.

    /**
     * @return {{myNum: number, myObject}}
     * An anonymous type with the given type members.
     */
    function getTmpObject() {
        return {
            myNum: 2,
            myObject: 0 || undefined || {}
        }
    }

Про @returnвикористання тегів {{field1: Number, field2: String}}див. На веб-сторінці : http://wiki.servoy.com/display/public/DOCS/Annotating+JavaScript+using+JSDoc

Якщо очікується, що параметр має певне властивість, ви можете документувати це властивість, надавши додатковий тег @param. Наприклад, якщо очікується, що параметр співробітника має властивості імені та відділу, ви можете його документувати так:

/**
 * Assign the project to a list of employees.
 * @param {Object[]} employees - The employees who are responsible for the project.
 * @param {string} employees[].name - The name of an employee.
 * @param {string} employees[].department - The employee's department.
 */
function(employees) {
    // ...
}

Якщо параметр зруйнований без явного імені, ви можете надати об'єкту відповідний і задокументувати його властивості.

/**
 * Assign the project to an employee.
 * @param {Object} employee - The employee who is responsible for the project.
 * @param {string} employee.name - The name of the employee.
 * @param {string} employee.department - The employee's department.
 */
Project.prototype.assign = function({ name, department }) {
    // ...
};

Джерело: JSDoc

Новий @configтег для цих випадків. Вони посилаються на попереднє @param.

/** My function does X and Y.
    @params {object} parameters An object containing the parameters
    @config {integer} setting1 A required setting.
    @config {string} [setting2] An optional setting.
    @params {MyClass~FuncCallback} callback The callback function
*/
function(parameters, callback) {
    // ...
};

/**
 * This callback is displayed as part of the MyClass class.
 * @callback MyClass~FuncCallback
 * @param {number} responseCode
 * @param {string} responseMessage
 */