Tham số hàm bị hủy tài liệu trong JSDoc

Trước đây, tôi luôn ghi lại các thông số đối tượng của mình như sau:

/**
 * Description of the function
 *
 * @param {Object} config - The configuration
 * @param {String} config.foo
 * @param {Boolean} [config.bar] - Optional value
 * @return {String}
 */
function doSomething (config = {}) {
  const { foo, bar } = config;
  console.log(foo, bar);
  // do something
}

Nhưng tôi không chắc cách tiếp cận tốt nhất với tham số hàm được mô tả là gì. Tôi chỉ bỏ qua đối tượng, xác định nó bằng cách nào đó hay cách tốt nhất để ghi lại nó là gì?

/**
 * Description of the function
 *
 * @param {String} foo
 * @param {Boolean} [bar] - Optional value
 * @return {String}
 */
function doSomething ({ foo, bar } = {}) {
  console.log(foo, bar);
  // do something
}

Tôi cảm thấy như cách tiếp cận của tôi ở trên không làm cho nó rõ ràng rằng hàm mong đợi một objecttham số chứ không phải hai tham số khác nhau.

Một cách khác mà tôi có thể nghĩ ra sẽ sử dụng @typedef, nhưng điều đó có thể trở thành một mớ hỗn độn lớn (đặc biệt là trong một tệp lớn hơn với nhiều phương thức)?

/**
 * @typedef {Object} doSomethingConfiguration
 * @property {String} foo
 * @property {Boolean} [bar] - Optional value
 */

/**
 * Description of the function
 *
 * @param {doSomethingConfiguration}
 * @return {String}
 */
function doSomething ({ foo, bar } = {}) {
  console.log(foo, bar);
  // do something
}

Đây là cách nó dự định, như được mô tả trong tài liệu .

/**
 * My cool function.
 *
 * @param {Object} obj - An object.
 * @param {string} obj.prop1 - Property 1.
 * @param {string} obj.prop2 - Property 2.
 */
var fn = function ({prop1, prop2}) {
  // Do something with prop1 and prop2
}

Vì vậy, ví dụ đầu tiên của bạn là khá nhiều chính xác.

Một ví dụ khác với một số lồng ghép sâu hơn:

/**
 * Nesting example.
 *
 * @param {object} param
 * @param {number} param.a - First value
 * @param {object} param.b - Wrapper
 * @param {number} param.b.c - Second value
 * @return {number} sum a and b
 */
letters = ({a, b: {c}}) => a + c;

Cá nhân tôi sử dụng cái này:

/**
* @param {{
  a: number
  b: number
}} param0
* @returns {number} The sum
*/
const func = ({ a, b }) => a + b;

Chỉ cần tạo đối tượng ngay tại đó.

Tôi cũng tận dụng nguyên cảo , và sẽ tuyên bố obtional bnhư b?hay b: number | undefinednhư JSDoc cũng cho phép công đoàn

Xem "Tài liệu hóa thuộc tính của tham số" của JSDoc :

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

( Kiểm tra loại trình biên dịch Google Closure , dựa trên nhưng được chuyển hướng từ JSDoc, cũng cho phép @param {{x:number,y:number}} point A "point-shaped" object.)