jsdoc에서 "object" 인수를 어떻게 설명합니까?

jsdoc에서 "object" 인수를 어떻게 설명합니까?

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

---

이전에는 대응하는 @param 바로 뒤에 @config 태그가 있었는데, 이 태그는 폐지된 것 같습니다(여기 예).

지금까지 객체를 파라미터/타입으로 문서화하는 방법은 4가지가 있습니다.저마다 용도가 있다.단, 이들 중 3개만 반환값을 문서화할 수 있습니다.

기존 속성 세트를 가진 객체의 경우(변수 A)

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

이 구문은 이 함수의 매개 변수로만 사용되며 각 속성에 대한 자세한 설명이 필요하지 않은 개체에 적합합니다.이것도 쓸 수 있어요.

알려진 속성 세트를 가진 객체의 경우(변수 B)

속성 구문을 사용하는 파라미터는 매우 유용합니다.

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

이 구문은 이 함수의 매개 변수로만 사용되며 각 속성에 대한 자세한 설명이 필요한 개체에 적합합니다.이것은 다음에 사용할 수 없습니다.@returns.

소스에서 둘 이상의 포인트에서 사용되는 객체의 경우

이 경우 @typedef는 매우 편리합니다.소스 내의 한 지점에서 유형을 정의하여 다음 유형에 사용할 수 있습니다.@param ★★★★★★★★★★★★★★★★★」@returnsJSDoc.

/**
 * @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뿐만 아니라.

자원.

문서 유형에 대한 유용한 정보는 다음 URL에서 찾을 수 있습니다.

https://jsdoc.app/module-type.module

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

  https://google.github.io/styleguide/javascriptguide.xml#JsTypes에 따르면 가능한 JSDoc

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

  https://groups.google.com/forum/ #!topic/jsdoc-users/TMVUedK9tC4에 따라 JSDoc이 가능합니다.

  • 허세를 부리다.

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

언급URL : https://stackoverflow.com/questions/6460604/how-to-describe-object-arguments-in-jsdoc