Parameter fungsi yang dirusak dokumen di JSDoc

90

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 objectdan 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
}
morkro
sumber
1
Saya pikir pendekatan pertama masih bagus. Tidak ada yang peduli apakah objek diberi nama configdalam kode Anda atau memang memiliki nama sama sekali.
Bergi
Di WebStorm saya telah menemukan bahwa jika saya hanya mendeskripsikan parameter (after-destructuring) dan mengabaikan destrukturisasi, sebagian besar berfungsi kecuali untuk kasus yang kurang umum. Jadi dalam contoh Anda, gambarkan dua parameter foodan bar. 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.
Mörre

Jawaban:

96

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;
Cerbrus
sumber
Saya tidak melihat bagaimana JSDoc bekerja dengan jelas ketika Anda memiliki beberapa argumen yang rusak, seperti function ({a}, {a}) {}. JSDoc saya kira akan @param {object} param1, @param {*} param1.a, @param {object} param2, @param {*} param2.a, dan bergantung pada urutan @paramtag?
ZachB
@ZachB: function ({a}, {a}) {}adalah sintaks yang tidak valid, karena aditentukan dua kali, di sana.
Cerbrus
1
Ups. ({a: b}, {a}))atau ({a}, {b})- maksudnya adalah bahwa @paramtag 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.
ZachB
1
Terima kasih, @ d0gb3r7. Saya telah memperbarui tautan di jawaban.
Cerbrus
10

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 bsebagai b?atau b: number | undefinedkarena JSDoc juga mengizinkan serikat pekerja

Coding Edgar
sumber
-8

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

Jakub Holý
sumber
2
Bukankah dia sudah melakukan itu? Dia bertanya apa yang harus dilakukan sekarang karena tidak ada employeevariabel lagi dalam fungsi.
Bergi
7
Ini tidak menjawab pertanyaan - contoh ini tidak menggunakan destrukturisasi! Dengan penghancuran Anda tidak memiliki objek induk.
Mörre
Sebenarnya tautannya sama, tepat setelah contohnya memberikan contoh relatif dengan komentar jsdoc yang sama persis untuk 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."
notacouch