如何在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) {
}

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)
}

Answer 1

From the @param wiki page :

---

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 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 ).

Answer 2

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.

For objects with a known set of properties (Variant 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 @returns as well .

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

Very useful is the parameters with properties syntax:

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

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

In this case a @typedef comes in very handy. You can define the type at one point in your source and use it as a type for @param or @returns or other JSDoc tags that can make use of a type.

/**
 * @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 @param tag:

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

Or in a @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 @returns as well.

Resources

Useful information about documenting types can be found here:

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

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

Answer 3

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

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.

• 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 tohttps://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 tohttps://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 tohttps://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 || {} } }

Answer 4

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

Answer 5

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:

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

Answer 6

There's a new @config tag for these cases. They link to the preceding @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
 */