Как описать «объектные» аргументы в jsdoc?

316
// 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)
}
Энди Хин
источник

Ответы:

428

Со страницы вики @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, но, похоже, он устарел ( пример здесь ).

Джонни Бьюкенен
источник
17
к сожалению, тег возвратов, похоже, не имеет эквивалентного code.google.com/p/jsdoc-toolkit/wiki/TagReturns
Майкл Билстра,
1
В этом аналогичном ответе stackoverflow.com/a/14820610/3094399 они также добавили параметры @param {Object} в начале. Думаю, это может быть излишним.
pcatre
У вас есть какой-нибудь пример с параметрами разрушения ES6? В моем случае у меня нет actionимени, я пишу `foo = ({arg1, arg2, arg2}) => {...}`. Изменить: здесь вопрос stackoverflow.com/questions/36916790/…
Эрик Бурел
Любая идея, как документировать член объекта, который является вариантом? Я имею в виду, что мой пользовательский объект должен иметь имя пользователя и может иметь полное имя. так как мне указать, что полное имя необязательно
Yash Kumar Verma
167

К настоящему времени существует 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
 */
Саймон Зикс
источник
Вариант 1 работает с несколькими типами свойства? Как {{dir: A|B|C }}?
CMCDragonkai
Любая аннотация должна быть здесь, так что да
Саймон Зикс
А для объектов, чьи ключи генерируются динамически? Лайк{[myVariable]: string}
Фрондор
135

Я вижу, что уже есть ответ о теге @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 || {}
          }
      }
vogdb
источник
Кто-нибудь знает способ создания этого в IntelliJ / Webstorm? Конкретно я говорю о третьем варианте - определить тип.
Эрез Коэн
Пожалуйста, дополните. Хотите ли вы иметь какие-либо горячие клавиши или ярлыки в IDE для создания этих документов, или вы хотите, чтобы ваша IDE понимала эти документы? Возможно оба?
vogdb
@vogdb, не могли бы вы взглянуть на этот вопрос? Я полагаю, что этот вариант использования не охватывается вашими прекрасными примерами: stackoverflow.com/questions/53191739/…
Павел Поляков
@PavelPolyakov Я посмотрел. Я действительно не знаю, как ответить на ваш вопрос. Я вышел из JS на некоторое время. Не стесняйтесь редактировать мой ответ, если у вас есть новая информация.
vogdb
2

Если ожидается, что параметр имеет определенное свойство, вы можете задокументировать это свойство, указав дополнительный тег @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

Карма Блэкшоу
источник
0

Для @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
 */
Майк ДеСимоне
источник
1
Можете ли вы указать на документацию для @configтега? Я не нашел ничего на usejsdoc.org , и эта страница предполагает, @configчто она устарела.
Дан Даскалеску
4
Я думаю, что @configне рекомендуется на этом этапе. YUIDoc рекомендует использовать @attributeвместо этого.
Майк ДеСимон,