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

小开

最佳答案

带属性的参数

如果一个参数希望有一个特定的属性，你可以在参数的@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后面，但它似乎已被弃用(例子)。

小开

对于@return标记使用\{\{field1: Number, field2: String}}，参见:http://wiki.servoy.com/display/public/DOCS/Annotating+JavaScript+using+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
*/

小开

我看到已经有一个关于@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
}
```

Function returns object where keys are known constants. Example: {id: 1, title: 'Hello world', type: 'LEARN', children: {...}}. We can easily access properties of this object: object.id.

Possible JSDoc according to https://groups.google.com/forum/#!topic/jsdoc-users/TMvUedK9tC4

Fake It.

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

Define a type.

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

According to https://google.github.io/styleguide/javascriptguide.xml#JsTypes

The record type.

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

小开

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

对于具有一组已知属性的对象(变体a)

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

此语法对于仅用作此函数的参数且不需要进一步描述每个属性的对象非常理想。可以用于@returns以及。< / p >

对于具有一组已知属性的对象(变体B)

具有属性的参数语法非常有用:

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

小开

如果期望一个参数具有特定的属性，则可以通过提供额外的@param标记来记录该属性。例如，如果一个employee参数希望具有名称和部门属性，您可以按照以下方式记录它:

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