JSDoc 必需参数和默认值

Question

我在 JSDoc 中发现 following for document 是一个可选参数。:

/**
 * @param {string} [somebody=John Doe] - Somebody's name.
 */
function sayHello(somebody) {
    if (!somebody) {
        somebody = 'John Doe';
    }
    alert('Hello ' + somebody);
}

这是文档参数对象属性。

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

现在我想在 JSDoc 中记录一个必需的对象参数。像这样。:

/**
 * Assign the project to an employee.
 * @param {Object} employee - The employee who is responsible for the project.
 * @param {string} employee.name=John Doe - The name of the employee.
 * @param {string} employee.department - The employee's department.
 */
Project.prototype.assign = function(employee) {
    // ...
};

我该怎么做？

也许解决方案 @param {string} employee.name=John Doe - The name of the employee. 已经是正确的？

Answer 1

你是对的。根据 http://usejsdoc.org/tags-param.html 中的 "Parameters with properties"：

If a parameter is expected to have a specific property, you can document that property by providing an additional @param tag.

但是，如果您要在其他函数中重复使用这些属性，您可能需要定义一个 Employee 类型：

/**
 * The employee who is responsible for the project
 * @typedef {Object} Employee
 * @property {string} name - The name of the employee
 * etc.
 */

/*
 * @param {Employee} employee - The employee who is responsible for the project.
 */
Project.prototype.assign = function(employee) {

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

JSDoc 必需参数和默认值

JSDoc required parameter with default value

javascript

documentation

jsdoc