Sebelumnya saya selalu mendokumentasikan parameter objek saya sebagai berikut:
/**
* 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
}
Tapi saya tidak yakin apa pendekatan terbaik dengan parameter fungsi desctructured. Apakah saya mengabaikan objeknya, mendefinisikannya dengan cara apa pun, atau cara terbaik untuk mendokumentasikannya?
/**
* Description of the function
*
* @param {String} foo
* @param {Boolean} [bar] - Optional value
* @return {String}
*/
function doSomething ({ foo, bar } = {}) {
console.log(foo, bar);
// do something
}
Saya merasa pendekatan saya di atas tidak membuatnya jelas bahwa fungsi mengharapkan object
dan bukan dua parameter yang berbeda.
Cara lain yang dapat saya pikirkan adalah menggunakan @typedef
, tetapi itu mungkin akan menjadi kekacauan besar (terutama dalam file yang lebih besar dengan banyak metode)?
/**
* @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
}
config
dalam kode Anda atau memang memiliki nama sama sekali.foo
danbar
. Ini bukan solusi akhir, tetapi pendekatan apa pun yang menggunakan objek menghasilkan kesalahan inspeksi - dan inspeksi serta pelengkapan otomatis dari IDE adalah hal yang paling saya pedulikan.Jawaban:
Beginilah tujuannya, seperti yang dijelaskan dalam dokumentasi .
/** * 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 }
Jadi, contoh pertama Anda cukup benar.
Contoh lain dengan beberapa sarang yang lebih dalam:
/** * 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;
sumber
function ({a}, {a}) {}
. JSDoc saya kira akan@param {object} param1, @param {*} param1.a, @param {object} param2, @param {*} param2.a
, dan bergantung pada urutan@param
tag?function ({a}, {a}) {}
adalah sintaks yang tidak valid, karenaa
ditentukan dua kali, di sana.({a: b}, {a}))
atau({a}, {b})
- maksudnya adalah bahwa@param
tag JSDoc adalah AFAIK tanpa urutan dan kuncinya dapat menjadi ambigu jika JSDoc mencoba mencocokkan menggunakan nama properti. Versi VSCode berikutnya akan menggunakan pencarian posisi untuk menyelesaikan skenario ini.Saya pribadi menggunakan yang ini:
/** * @param {{ a: number b: number }} param0 * @returns {number} The sum */ const func = ({ a, b }) => a + b;
Buat saja objeknya di sana.
Saya juga memanfaatkan TypeScript , dan akan menyatakan obtional
b
sebagaib?
ataub: number | undefined
karena JSDoc juga mengizinkan serikat pekerjasumber
Lihat "Mendokumentasikan properti parameter" 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) { // ... };
( Pemeriksaan jenis penyusun Google Closure , yang didasarkan pada tetapi dialihkan dari JSDoc, juga memungkinkan
@param {{x:number,y:number}} point A "point-shaped" object.
)sumber
employee
variabel lagi dalam fungsi.Project.prototype.assign = function({ name, department })
. Sebelum contoh, mereka mengatakan, "Jika parameter dihancurkan tanpa nama eksplisit, Anda dapat memberikan objek yang sesuai dan mendokumentasikan propertinya."