How to describe "object" arguments in jsdoc?

user_396077 0
Viewed 222355
// 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)
}
jsdoc javascript
6 Answers

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

user_87491490
Related