พารามิเตอร์ฟังก์ชันทำลายโครงสร้างเอกสารใน JSDoc


90

ก่อนหน้านี้ฉันได้บันทึกพารามิเตอร์ออบเจ็กต์ของฉันไว้เสมอดังนี้:

/**
 * 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
}

แต่ฉันไม่แน่ใจว่าแนวทางที่ดีที่สุดคืออะไรกับพารามิเตอร์ฟังก์ชัน desctructured ฉันจะเพิกเฉยต่อวัตถุกำหนดหรือไม่หรือวิธีใดเป็นวิธีที่ดีที่สุดในการจัดทำเอกสาร

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

ฉันรู้สึกว่าแนวทางของฉันข้างต้นไม่ได้ทำให้ชัดเจนว่าฟังก์ชั่นคาดหวังobjectและไม่ใช่สองพารามิเตอร์ที่แตกต่างกัน

อีกวิธีหนึ่งที่ฉันคิดว่าจะใช้@typedefแต่นั่นอาจเป็นเรื่องยุ่งมาก (โดยเฉพาะในไฟล์ขนาดใหญ่ที่มีหลายวิธี)?

/**
 * @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
}

1
ฉันคิดว่าแนวทางแรกยังคงใช้ได้ ไม่มีใครสนใจว่าวัตถุนั้นจะถูกตั้งชื่อconfigในรหัสของคุณหรือไม่หรือมีชื่อใด ๆ เลย
Bergi

ใน WebStorm ฉันพบว่าถ้าฉันเพียงแค่อธิบายพารามิเตอร์ (หลังการทำลายโครงสร้าง) และเพิกเฉยต่อการทำลายโครงสร้างส่วนใหญ่จะใช้ได้ผลยกเว้นกรณีที่ไม่ค่อยพบบ่อย ดังนั้นในตัวอย่างของคุณอธิบายพารามิเตอร์สองตัวfooและbar. ไม่ใช่วิธีการแก้ปัญหาขั้นสุดท้าย แต่วิธีใดก็ตามที่ใช้ข้อผิดพลาดในการตรวจสอบวัตถุและการตรวจสอบและการเติมข้อความอัตโนมัติจาก IDE คือสิ่งที่ฉันสนใจมากที่สุด
Mörre

คำตอบ:


96

นี่คือวิธีที่มันตั้งใจที่อธิบายไว้ในเอกสาร

/**
 * 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
}

ดังนั้นตัวอย่างแรกของคุณจึงค่อนข้างถูกต้อง

อีกตัวอย่างหนึ่งของการทำรังที่ลึกขึ้น:

/**
 * 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;

ฉันไม่เห็นว่า JSDoc ทำงานได้อย่างไม่น่าสงสัยเมื่อคุณมีอาร์กิวเมนต์ที่ทำลายโครงสร้างหลายรายการเช่นfunction ({a}, {a}) {}. ฉันคิดว่า JSDoc จะเป็น@param {object} param1, @param {*} param1.a, @param {object} param2, @param {*} param2.aและพึ่งพาการสั่ง@paramแท็กหรือไม่?
ZachB

@ZachB: function ({a}, {a}) {}เป็นไวยากรณ์ที่ไม่ถูกต้องเนื่องจากaถูกกำหนดไว้สองครั้งที่นั่น
Cerbrus

1
อ๊ะ. ({a: b}, {a}))หรือ({a}, {b})- ประเด็นคือ@paramแท็กJSDoc เป็น AFAIK ที่ไม่เป็นระเบียบและคีย์อาจคลุมเครือได้คือ JSDoc พยายามจับคู่โดยใช้ชื่อคุณสมบัติ VSCode เวอร์ชันถัดไปจะใช้การค้นหาตำแหน่งเพื่อแก้ไขสถานการณ์นี้
ZachB

1
ขอบคุณ @ d0gb3r7 ฉันได้อัปเดตลิงก์ในคำตอบแล้ว
Cerbrus

10

ฉันใช้อันนี้เป็นการส่วนตัว:

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

เพียงแค่สร้างวัตถุตรงนั้น

ฉันยังใช้ประโยชน์จาก TypeScriptและจะประกาศ obtional bเป็นb?หรือb: number | undefinedเนื่องจากJSDoc อนุญาตให้มีสหภาพแรงงานด้วย


-8

ดู"การบันทึกคุณสมบัติของพารามิเตอร์" ของ 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) {
    // ...
};

( การตรวจสอบประเภทคอมไพเลอร์ Google Closureซึ่งขึ้นอยู่กับ แต่เบี่ยงเบนจาก JSDoc ก็อนุญาตเช่นกัน@param {{x:number,y:number}} point A "point-shaped" object.)


2
เขาไม่ทำแบบนั้นแล้วเหรอ? เขากำลังถามว่าจะทำอย่างไรตอนนี้ที่ไม่มีemployeeตัวแปรในฟังก์ชันอีกต่อไป
Bergi

7
นี่ไม่ตอบคำถาม - ตัวอย่างนี้ไม่ใช้การทำลายล้าง! ด้วยการทำลายโครงสร้างคุณไม่มีวัตถุหลัก
Mörre

อันที่จริงการเชื่อมโยงของเขาเหมือนกันทันทีหลังจากตัวอย่างของเขาให้เป็นตัวอย่างที่ญาติกับความคิดเห็น jsdoc Project.prototype.assign = function({ name, department })เดียวกันแน่นอนสำหรับ ก่อนที่ตัวอย่างจะกล่าวว่า "หากพารามิเตอร์ถูกทำลายโดยไม่มีชื่อที่ชัดเจนคุณสามารถกำหนดอ็อบเจ็กต์ที่เหมาะสมและบันทึกคุณสมบัติของมันได้"
notacouch
โดยการใช้ไซต์ของเรา หมายความว่าคุณได้อ่านและทำความเข้าใจนโยบายคุกกี้และนโยบายความเป็นส่วนตัวของเราแล้ว
Licensed under cc by-sa 3.0 with attribution required.