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

Posted 2023-03-11

【中文标题】如何在 jsdoc 中描述“对象”参数？

【英文标题】：How to describe "object" arguments in jsdoc?

【发布时间】：2011-09-21 13:58:08

【问题描述】：

// 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 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）。

【讨论】：

不幸的是，returns 标签似乎没有等效的code.google.com/p/jsdoc-toolkit/wiki/TagReturns

在这个类似的答案***.com/a/14820610/3094399 中，他们还在开头添加了@param Object 选项。不过我猜这可能是多余的。

知道如何记录作为选项的对象成员吗？我的意思是我的用户对象应该有用户名，并且可以有全名。那么如何指定全名是可选的

【参考方案2】：

到目前为止，有 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
 */

【讨论】：

变体 1 是否适用于多种类型的属性？喜欢dir: A|B|C ？

这里应该可以使用任何类型注释，所以是的

对于动态生成键的对象呢？喜欢[myVariable]: string

vscode（1.51以下）不能很好地处理@typedef，它不能显示提示的对象属性，到目前为止我坚持使用param Object

vscode 现在可以正常使用 @typedef 方法了。

【参考方案3】：

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

满月。

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

【参考方案4】：

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

【讨论】：

原始链接没有任何用处。我相信它的新版本在这里：wiki.servoy.com/display/Serv7/Annotating+JavaScript+Using+JSDoc

【参考方案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

【参考方案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
 */

【讨论】：

您能指出@config 标签的文档吗？我找到了nothing on usejsdoc.org，而this page 表明@config 已被弃用。

我认为 @config 在这一点上已被弃用。 YUIDoc recommends using @attribute instead.