关于javascript：如何在jsdoc中描述“对象”参数？


How to describe “object” arguments in jsdoc?

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

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

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

从@param Wiki页面：

具有属性的参数

如果期望某个参数具有特定的属性，则可以在该参数的@param标记后立即对其进行记录，如下所示：

1
2
3
4
5
6
7
8
 /**
  * @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标记的答案已经存在，但是我想提供更多有关它的详细信息。

首先，官方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

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    /**
     * @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

    • 假装。

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      /**
       * 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
          }
      }

    • 光猪六壮士。

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17
      18
      19
      20
      21
      22
      23
      /**
       @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);
      }

    • 定义类型。

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
      16
      17
      18
      19
      20
      /**
       @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

    • 记录类型。

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      /**
       * @return {{myNum: number, myObject}}
       * An anonymous type with the given type members.
       */
      function getTmpObject() {
          return {
              myNum: 2,
              myObject: 0 || undefined || {}
          }
      }
相关讨论

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

对于具有一组已知属性的对象(变量A)

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

对于仅用作该函数参数且不需要进一步描述每个属性的对象，此语法是理想的。
它也可以用于@returns。

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

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

1
2
3
4
5
6
/**
 * @param {Object} myObj description
 * @param {number} myObj.a description
 * @param {string} myObj.b description
 * @param {} myObj.c description
 */

对于仅用作该函数参数且需要进一步描述每个属性的对象，此语法是理想的。
不能用于@returns。

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

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

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

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

1
2
3
/**
 * @param {Person} p - Description of p
 */

或在@returns中：

1
2
3
/**
 * @returns {Person} Description
 */

对于所有值都属于同一类型的对象

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

第一种类型(字符串)记录了键的类型，这些键的类型在JavaScript中始终为字符串，或者至少始终会强制为字符串。第二种类型(数字)是值的类型；这可以是任何类型。
此语法也可以用于@returns。

资源资源

有关文档类型的有用信息，可以在这里找到：

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

PS：

要记录可选值，可以使用[]：

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

要么：

1
2
3
/**
 * @param {number|undefined} opt_number this number is optional
 */
相关讨论

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

相关讨论

这些情况下有一个新的@config标记。它们链接到前面的@param。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
/** 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
 */
相关讨论