วิธีอธิบายอาร์กิวเมนต์“ object” ใน jsdoc ได้อย่างไร

// My function does X and Y.
// @params {object} parameters An object containing the parameters
// @params {function} callback The callback function
function(parameters, callback) {
}

แต่ฉันจะอธิบายได้อย่างไรว่าวัตถุพารามิเตอร์ควรมีโครงสร้างอย่างไร ตัวอย่างเช่นควรมีลักษณะดังนี้:

{
  setting1 : 123, // (required, integer)
  setting2 : 'asdf' // (optional, string)
}

จากหน้า@param wiki :

พารามิเตอร์พร้อมคุณสมบัติ

หากคาดว่าพารามิเตอร์จะมีคุณสมบัติเฉพาะคุณสามารถทำเอกสารนั้นทันทีหลังจากแท็ก @param สำหรับพารามิเตอร์นั้นเช่น:

 /**
  * @param userInfo Information about the user.
  * @param userInfo.name The name of the user.
  * @param userInfo.email The email of the user.
  */
 function logIn(userInfo) {
        doLogIn(userInfo.name, userInfo.email);
 }

เคยมีแท็ก @config ซึ่งตามด้วย @param ที่เกี่ยวข้องทันที แต่ดูเหมือนว่าเลิกใช้แล้ว ( ตัวอย่างที่นี่ )

ถึงตอนนี้มี 4 วิธีในการจัดทำเอกสารวัตถุเป็นพารามิเตอร์ / ประเภท แต่ละคนมีการใช้งานของตัวเอง มีเพียง 3 รายการเท่านั้นที่สามารถใช้เพื่อบันทึกค่าส่งคืนได้

สำหรับวัตถุที่มีชุดคุณสมบัติที่รู้จัก (Variant A)

/**
 * @param {{a: number, b: string, c}} myObj description
 */

ไวยากรณ์นี้เหมาะสำหรับวัตถุที่ใช้เป็นพารามิเตอร์สำหรับฟังก์ชันนี้เท่านั้นและไม่ต้องการคำอธิบายเพิ่มเติมของคุณสมบัติแต่ละรายการ มันสามารถใช้สำหรับการ@returnsได้เป็นอย่างดี

สำหรับวัตถุที่มีชุดคุณสมบัติที่รู้จัก (Variant B)

มีประโยชน์มากคือพารามิเตอร์ที่มีไวยากรณ์ของคุณสมบัติ :

/**
 * @param {Object} myObj description
 * @param {number} myObj.a description
 * @param {string} myObj.b description
 * @param {} myObj.c description
 */

ไวยากรณ์นี้เหมาะสำหรับวัตถุที่ใช้เป็นพารามิเตอร์สำหรับฟังก์ชันนี้เท่านั้นและต้องการคำอธิบายเพิ่มเติมของแต่ละคุณสมบัติ @returnsนี้ไม่สามารถนำมาใช้สำหรับ

สำหรับวัตถุที่จะใช้มากกว่าหนึ่งจุดในแหล่งที่มา

ในกรณีนี้@typedefมีประโยชน์มาก คุณสามารถกำหนดประเภทที่จุดหนึ่งในแหล่งที่มาของคุณและใช้เป็นประเภทสำหรับ@paramหรือ@returnsหรือแท็ก JSDoc อื่น ๆ ที่สามารถใช้ประเภท

/**
 * @typedef {Object} Person
 * @property {string} name how the person is called
 * @property {number} age how many years the person lived
 */

จากนั้นคุณสามารถใช้สิ่งนี้ใน@paramแท็ก:

/**
 * @param {Person} p - Description of p
 */

หรือใน@returns:

/**
 * @returns {Person} Description
 */

สำหรับวัตถุที่มีค่าเป็นประเภทเดียวกันทั้งหมด

/**
 * @param {Object.<string, number>} dict
 */

ประเภทแรก (สตริง) เอกสารประเภทของคีย์ซึ่งใน JavaScript เป็นสตริงเสมอหรืออย่างน้อยก็จะถูกบังคับให้สตริง ชนิดที่สอง (หมายเลข) คือชนิดของค่า นี่อาจเป็นประเภทใดก็ได้ ไวยากรณ์นี้สามารถใช้สำหรับ@returnsเช่นกัน

ทรัพยากร

ข้อมูลที่เป็นประโยชน์เกี่ยวกับประเภทเอกสารสามารถดูได้ที่นี่:

https://jsdoc.app/tags-type.html

PS:

เพื่อบันทึกค่าเผื่อเลือกที่คุณสามารถใช้ได้[]:

/**
 * @param {number} [opt_number] this number is optional
 */

หรือ:

/**
 * @param {number|undefined} opt_number this number is optional
 */

ฉันเห็นว่ามีคำตอบเกี่ยวกับแท็ก @return แล้ว แต่ฉันต้องการให้รายละเอียดเพิ่มเติมเกี่ยวกับแท็กนี้

ก่อนอื่นเอกสารทางการของ JSDoc 3 ไม่ได้ให้ตัวอย่างเกี่ยวกับ @return สำหรับวัตถุที่กำหนดเอง โปรดดูhttps://jsdoc.app/tags-returns.html ทีนี้มาดูกันว่าเราจะทำอะไรได้บ้างจนกว่ามาตรฐานจะปรากฏขึ้น

• ฟังก์ชั่นส่งคืนวัตถุที่มีการสร้างคีย์แบบไดนามิก ตัวอย่าง: {1: 'Pete', 2: 'Mary', 3: 'John'}. for(var key in obj){...}ปกติเราย้ำกว่าวัตถุนี้ด้วยความช่วยเหลือของ

  JSDoc เป็นไปได้ตามhttps://google.github.io/styleguide/javascriptguide.xml#JsTypes

  /**
   * @return {Object.<number, string>}
   */
  function getTmpObject() {
      var result = {}
      for (var i = 10; i >= 0; i--) {
          result[i * 3] = 'someValue' + i;
      }
      return result
  }

• ฟังก์ชั่นส่งกลับวัตถุที่คีย์เป็นที่รู้จักกันอยู่ ตัวอย่าง: {id: 1, title: 'Hello world', type: 'LEARN', children: {...}}. object.idเราสามารถเข้าถึงได้อย่างง่ายดายคุณสมบัติของวัตถุนี้:

  เป็นไปได้ JSDoc ตามhttps://groups.google.com/forum/#!topic/jsdoc-users/TMvUedK9tC4

  • ปลอม.

    /**
     * Generate a point.
     *
     * @returns {Object} point - The point generated by the factory.
     * @returns {number} point.x - The x coordinate.
     * @returns {number} point.y - The y coordinate.
     */
    var pointFactory = function (x, y) {
        return {
            x:x,
            y:y
        }
    }

  • ฟูลมอนตี้

    /**
     @class generatedPoint
     @private
     @type {Object}
     @property {number} x The x coordinate.
     @property {number} y The y coordinate.
     */
    function generatedPoint(x, y) {
        return {
            x:x,
            y:y
        };
    }
    
    /**
     * Generate a point.
     *
     * @returns {generatedPoint} The point generated by the factory.
     */
    
    var pointFactory = function (x, y) {
        return new generatedPoint(x, y);
    }

  • กำหนดประเภท

    /**
     @typedef generatedPoint
     @type {Object}
     @property {number} x The x coordinate.
     @property {number} y The y coordinate.
     */
    
    
    /**
     * Generate a point.
     *
     * @returns {generatedPoint} The point generated by the factory.
     */
    
    var pointFactory = function (x, y) {
        return {
            x:x,
            y:y
        }
    }

  ตามhttps://google.github.io/styleguide/javascriptguide.xml#JsTypes

  • ประเภทบันทึก

    /**
     * @return {{myNum: number, myObject}}
     * An anonymous type with the given type members.
     */
    function getTmpObject() {
        return {
            myNum: 2,
            myObject: 0 || undefined || {}
        }
    }

สำหรับการ@returnใช้แท็ก{{field1: Number, field2: String}}โปรดดูที่: http://wiki.servoy.com/display/public/DOCS/Annotating+JavaScript+using+JSDoc

หากคาดว่าพารามิเตอร์จะมีคุณสมบัติเฉพาะคุณสามารถจัดทำเอกสารคุณสมบัตินั้นได้โดยระบุแท็ก @param เพิ่มเติม ตัวอย่างเช่นหากคาดว่าพารามิเตอร์พนักงานจะมีคุณสมบัติชื่อและแผนกคุณสามารถจัดทำเอกสารดังต่อไปนี้:

/**
 * Assign the project to a list of employees.
 * @param {Object[]} employees - The employees who are responsible for the project.
 * @param {string} employees[].name - The name of an employee.
 * @param {string} employees[].department - The employee's department.
 */
function(employees) {
    // ...
}

หากพารามิเตอร์ถูกทำลายโดยไม่มีชื่อที่ชัดเจนคุณสามารถให้วัตถุที่เหมาะสมและเอกสารคุณสมบัติของมัน

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

ที่มา: JSDoc

มี@configแท็กใหม่สำหรับกรณีเหล่านี้ พวกเขาเชื่อมโยงไปยังก่อนหน้า@paramนี้

/** My function does X and Y.
    @params {object} parameters An object containing the parameters
    @config {integer} setting1 A required setting.
    @config {string} [setting2] An optional setting.
    @params {MyClass~FuncCallback} callback The callback function
*/
function(parameters, callback) {
    // ...
};

/**
 * This callback is displayed as part of the MyClass class.
 * @callback MyClass~FuncCallback
 * @param {number} responseCode
 * @param {string} responseMessage
 */