Làm thế nào để mô tả các đối số của người Viking đối số trong jsdoc?

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

Nhưng làm thế nào để tôi mô tả làm thế nào các đối tượng tham số nên được cấu trúc? Ví dụ, nó phải là một cái gì đó như:

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

Từ trang wiki @param :

Tham số có thuộc tính

Nếu một tham số dự kiến ​​sẽ có một thuộc tính cụ thể, bạn có thể ghi lại tài liệu đó ngay sau thẻ @param cho tham số đó, như sau:

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

Đã từng có một thẻ @config ngay sau @param tương ứng, nhưng dường như nó không được dùng nữa ( ví dụ ở đây ).

Cho đến nay, có 4 cách khác nhau để ghi lại các đối tượng dưới dạng tham số / loại. Mỗi cái có công dụng riêng. Tuy nhiên, chỉ có 3 trong số chúng có thể được sử dụng để ghi lại các giá trị trả về.

Đối với các đối tượng có tập thuộc tính đã biết (Biến A)

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

Cú pháp này lý tưởng cho các đối tượng chỉ được sử dụng làm tham số cho hàm này và không yêu cầu mô tả thêm về từng thuộc tính. Nó có thể được sử dụng @returnslà tốt .

Đối với các đối tượng có tập thuộc tính đã biết (Biến thể B)

Rất hữu ích là các tham số với cú pháp thuộc tính :

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

Cú pháp này lý tưởng cho các đối tượng chỉ được sử dụng làm tham số cho hàm này và yêu cầu mô tả thêm về từng thuộc tính. Điều này không thể được sử dụng cho @returns.

Đối với các đối tượng sẽ được sử dụng tại nhiều hơn một điểm trong nguồn

Trong trường hợp này, một @typedef rất tiện dụng. Bạn có thể xác định loại tại một điểm trong nguồn của mình và sử dụng nó làm loại cho @paramhoặc @returnshoặc các thẻ JSDoc khác có thể sử dụng loại.

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

Sau đó, bạn có thể sử dụng điều này trong một @paramthẻ:

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

Hoặc trong một @returns:

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

Đối với các đối tượng có giá trị là cùng loại

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

Loại (chuỗi) đầu tiên ghi lại loại khóa mà trong JavaScript luôn là một chuỗi hoặc ít nhất sẽ luôn bị ép buộc thành một chuỗi. Loại thứ hai (số) là loại giá trị; đây có thể là bất kỳ loại nào Cú pháp này có thể được sử dụng @returnslà tốt.

Tài nguyên

Thông tin hữu ích về các loại tài liệu có thể được tìm thấy ở đây:

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

Tái bút

để ghi lại một giá trị tùy chọn bạn có thể sử dụng []:

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

hoặc là:

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

Tôi thấy rằng đã có câu trả lời về thẻ @return, nhưng tôi muốn cung cấp thêm chi tiết về nó.

Trước hết, tài liệu chính thức của JSDoc 3 không cung cấp cho chúng tôi bất kỳ ví dụ nào về @return cho một đối tượng tùy chỉnh. Vui lòng xem https://jsdoc.app/tags-returns.html . Bây giờ, hãy xem những gì chúng ta có thể làm cho đến khi một số tiêu chuẩn sẽ xuất hiện.

• Hàm trả về đối tượng trong đó các khóa được tạo động. Ví dụ : {1: 'Pete', 2: 'Mary', 3: 'John'}. Thông thường, chúng tôi lặp lại đối tượng này với sự giúp đỡ củafor(var key in obj){...} .

  JSDoc có thể theo 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
  }

• Hàm trả về đối tượng trong đó các khóa được biết là hằng số. Ví dụ : {id: 1, title: 'Hello world', type: 'LEARN', children: {...}}. Chúng ta có thể dễ dàng truy cập các thuộc tính của đối tượng này : object.id.

  JSDoc có thể theo https://groups.google.com/forum/#!topic/jsdoc-users/TMvUedK9tC4

  • Làm giả nó.

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

  • Monty đầ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);
    }

  • Xác định một loại.

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

  Theo https://google.github.io/styleguide/javascriptguide.xml#JsTypes

  • Các loại hồ sơ.

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

Để @returnsử dụng thẻ {{field1: Number, field2: String}}, hãy xem: http://wiki.servoy.com/display/public/DOCS/Annotating+JavaScript+USE+JSDoc

Nếu một tham số dự kiến ​​sẽ có một thuộc tính cụ thể, bạn có thể ghi lại thuộc tính đó bằng cách cung cấp thêm thẻ @param. Ví dụ: nếu một tham số nhân viên dự kiến ​​sẽ có các thuộc tính tên và bộ phận, bạn có thể ghi lại nó như sau:

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

Nếu một tham số bị hủy mà không có tên rõ ràng, bạn có thể cung cấp cho đối tượng một đối tượng thích hợp và ghi lại các thuộc tính của nó.

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

Nguồn: JSDoc

Có một @configthẻ mới cho những trường hợp này. Họ liên kết đến trước @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
 */