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

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页面:

带属性的参数

如果预期参数具有特定属性,则可以在该参数的@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之后,但它似乎已被弃用(例如这里).

Answer 2

我看到已经有关于@return标签的答案,但我想提供更多关于它的细节.

首先,官方JSDoc 3文档没有给我们任何有关自定义对象的@return的示例.请参阅http://usejsdoc.org/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 || {}
        }
    }
    

Answer 3

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

对于具有已知属性集的对象(变体A)

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

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

对于具有已知属性集的对象(变体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 {Person} Description
 */

第一种类型(字符串)记录了键的类型,这些键在JavaScript中始终是一个字符串,或者至少总是被强制转换为字符串.第二种类型(数字)是值的类型; 这可以是任何类型.也可以使用此语法@returns.

资源

有关记录类型的有用信息可以在这里找到:

http://usejsdoc.org/tags-type.html

PS:

记录可以使用[]的可选值:

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

要么:

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