Как описать аргументы "object" в 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)
}

Ответы

Ответ 1

На странице @param wiki:

Параметры с свойствами

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

Ответ 2

Я вижу, что уже есть ответ о теге @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 || {}
    }
}

Ответ 3

К настоящему времени существует 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
 */

Ответ 4

Для тега @return используйте {{field1: Number, field2: String}}, см. http://wiki.servoy.com/display/public/DOCS/Annotating+JavaScript+using+JSDoc

Ответ 5

В этих случаях есть новый тег @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
 */