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

How to describe "object" arguments in jsdoc?

提问by Andy Hin

// My function does X and Y.
// @params {object} parameters An object containing the parameters
// @params {function} callback The callback function
function(parameters, callback) {
}

But how do I describe how the parameters object should be structured? For example it should be something like:

但是我该如何描述参数对象的结构呢？例如它应该是这样的：

{
  setting1 : 123, // (required, integer)
  setting2 : 'asdf' // (optional, string)
}

回答by Jonny Buchanan

From the @param wiki page:

从@param wiki 页面：

---

---

Parameters With Properties

带属性的参数

If a parameter is expected to have a particular property, you can document that immediately after the @param tag for that parameter, like so:

如果期望参数具有特定属性，则可以在该参数的 @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);
 }

---

---

There used to be a @config tag which immediately followed the corresponding @param, but it appears to have been deprecated (example here).

曾经有一个@config 标签紧跟在相应的@param 之后，但它似乎已被弃用（示例here）。

回答by Simon Zyx

By now there are 4 different ways to document objects as parameters/types. Each has its own uses. Only 3 of them can be used to document return values, though.

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

For objects with a known set of properties (Variant A)

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

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

This syntax is ideal for objects that are used only as parameters for this function and don't require further description of each property. It can be used for @returnsas well.

此语法非常适合仅用作此函数的参数且不需要对每个属性进行进一步描述的对象。它可用于@returns和。

For objects with a known set of properties (Variant B)

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

Very useful is the parameters with propertiessyntax:

非常有用的是带有属性语法的参数：

/**
 * @param {Object} myObj description
 * @param {number} myObj.a description
 * @param {string} myObj.b description
 * @param {} myObj.c description
 */

This syntax is ideal for objects that are used only as parameters for this function and that require further description of each property. This can not be used for @returns.

此语法非常适用于仅用作此函数的参数且需要对每个属性进行进一步描述的对象。这不能用于@returns.

For objects that will be used at more than one point in source

对于将在源中多个点使用的对象

In this case a @typedefcomes in very handy. You can define the type at one point in your source and use it as a type for @paramor @returnsor other JSDoc tags that can make use of a type.

在这种情况下，@typedef非常方便。您可以在源代码中的某个位置定义类型，并将其用作@param或@returns或其他可以使用类型的 JSDoc 标记的类型。

/**
 * @typedef {Object} Person
 * @property {string} name how the person is called
 * @property {number} age how many years the person lived
 */

You can then use this in a @paramtag:

然后你可以在@param标签中使用它：

/**
 * @param {Person} p - Description of p
 */

Or in a @returns:

或者在一个@returns：

/**
 * @returns {Person} Description
 */

For objects whose values are all the same type

对于值都是相同类型的对象

/**
 * @param {Object.<string, number>} dict
 */

The first type (string) documents the type of the keys which in JavaScript is always a string or at least will always be coerced to a string. The second type (number) is the type of the value; this can be any type. This syntax can be used for @returnsas well.

第一种类型（字符串）记录了键的类型，在 JavaScript 中它总是一个字符串，或者至少总是被强制转换为一个字符串。第二种类型（数字）是值的类型；这可以是任何类型。此语法也可用于@returns。

Resources

资源

Useful information about documenting types can be found here:

可以在此处找到有关文档类型的有用信息：

https://jsdoc.app/tags-type.html

https://jsdoc.app/tags-type.html

PS:

PS：

to document an optional value you can use []:

记录您可以使用的可选值[]：

/**
 * @param {number} [opt_number] this number is optional
 */

or:

或者：

/**
 * @param {number|undefined} opt_number this number is optional
 */

回答by vogdb

I see that there is already an answer about the @return tag, but I want to give more details about it.

我看到已经有关于@return 标签的答案，但我想提供更多详细信息。

First of all, the official JSDoc 3 documentation doesn't give us any examples about the @return for a custom object. Please see https://jsdoc.app/tags-returns.html. Now, let's see what we can do until some standard will appear.

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

• Function returns object where keys are dynamically generated. Example: {1: 'Pete', 2: 'Mary', 3: 'John'}. Usually, we iterate over this object with the help of for(var key in obj){...}.

  Possible JSDoc according to 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
  }
  

• 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 || {}
        }
    }
    

• 函数返回动态生成键的对象。例子：{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 || {}
        }
    }
    

回答by maliboo

For @returntag use {{field1: Number, field2: String}}, see: http://wiki.servoy.com/display/public/DOCS/Annotating+JavaScript+using+JSDoc

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

回答by Karma Blackshaw

If a parameter is expected to have a specific property, you can document that property by providing an additional @param tag. For example, if an employee parameter is expected to have name and department properties, you can document it as follows:

如果期望参数具有特定属性，则可以通过提供额外的 @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) {
    // ...
}

If a parameter is destructured without an explicit name, you can give the object an appropriate one and document its properties.

如果一个参数在没有明确名称的情况下被解构，您可以为该对象提供一个合适的名称并记录其属性。

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

Source: JSDoc

资料来源：JSDoc

回答by Mike DeSimone

There's a new @configtag for these cases. They link to the preceding @param.

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