Question

// 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)
}

Answer 1

来自@param wiki page：

带属性的参数

如果参数预计具有特定属性，则可以在该参数的@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之后，但它似乎已被弃用（example here）。

Answer 2

我看到@return标签已有答案，但我想提供更多相关细节。

首先，官方JSDoc 3文档没有给我们任何关于自定义对象的@return的示例。请参阅https://jsdoc.app/tags-returns.html。现在，让我们看看在出现一些标准之前我们可以做些什么。

函数返回动态生成键的对象。示例：{1: 'Pete', 2: 'Mary', 3: 'John'}。通常，我们在for(var key in obj){...}的帮助下迭代这个对象。

根据https://google.github.io/styleguide/javascriptguide.xml#JsTypes
可能的JSDoc
```
/**
 * @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。

根据https://groups.google.com/forum/#!topic/jsdoc-users/TMvUedK9tC4

可能的JSDoc

假冒。

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

The Full Monty。

/**
 @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 || {}
    }
}

Answer 3

到目前为止，有4种不同的方法可以将对象记录为参数/类型。每个都有自己的用途。但是，只有3个可用于记录返回值。

对于具有已知属性集的对象（变体A）

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

此语法非常适合仅用作此函数的参数的对象，并且不需要进一步描述每个属性。它can be used for @returns as well。

对于具有已知属性集的对象（变体B）

非常有用parameters with properties语法：

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

Answer 4

对于@return代码使用{{field1: Number, field2: String}}，请参阅：http://wiki.servoy.com/display/public/DOCS/Annotating+JavaScript+using+JSDoc

Answer 5

如果期望参数具有特定属性，则可以通过提供其他@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

Answer 6

这些案例有一个新的@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
 */

如何在jsdoc中描述“对象”参数？

6 个答案:

带属性的参数