jsdoc에서“객체”인수를 설명하는 방법?


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

답변:


428

로부터 파라미터 : 위키 페이지 :


속성이있는 매개 변수

매개 변수에 특정 특성이있을 것으로 예상되는 경우 다음과 같이 해당 매개 변수의 @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 태그가 있었지만 더 이상 사용되지 않는 것으로 보입니다 ( 예 : 여기 ).


17
불행하게도 반품 태그는 해당이하지 않는 것 code.google.com/p/jsdoc-toolkit/wiki/TagReturns을
마이클 Bylstra에게

1
이 비슷한 답변 stackoverflow.com/a/14820610/3094399 그들은 또한 @param {Object} 옵션을 처음에 추가했습니다. 그래도 중복 될 수 있다고 생각합니다.
pcatre

ES6 파괴 매개 변수에 대한 예가 있습니까? 제 경우에는 action이름 이 없으며 `foo = ({arg1, arg2, arg2}) => {...}`라고 씁니다. 편집 : 여기에 질문 stackoverflow.com/questions/36916790/…
Eric Burel

옵션 인 객체 멤버를 문서화하는 방법에 대한 아이디어가 있습니까? 내 사용자 개체는 사용자 이름을 가져야하며 전체 이름을 가질 수 있습니다. 전체 이름을 선택 사항으로 지정하려면 어떻게해야합니까
Yash Kumar Verma

167

이제는 개체를 매개 변수 / 유형으로 문서화하는 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

추신:

선택적 값을 문서화하려면 다음을 사용할 수 있습니다 [].

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

또는:

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

변형 1은 여러 유형의 속성에서 작동합니까? 처럼 {{dir: A|B|C }}?
CMCDragonkai

모든 유형의 주석이 여기에 가능해야합니다.
Simon Zyx

그리고 키가 동적으로 생성되는 객체의 경우? 처럼{[myVariable]: string}
Frondor

135

@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 || {}
          }
      }

IntelliJ / Webstorm에서 이것을 생성하는 방법을 알고 있습니까? 특히 세 번째 옵션에 대해 이야기하고 있습니다-유형을 정의하십시오.
Erez Cohen 2016

정교하게 작성하십시오. 해당 문서를 생성하기 위해 IDE에 단축키 또는 단축키가 있습니까? 아니면 IDE가 해당 문서를 이해하도록 하시겠습니까? 둘 다 될 수 있습니까?
vogdb

@vogdb이 문제를 살펴볼 수 있습니까? 나는이 사용 사례가 당신의 좋은 예와 함께 적용되지 않습니다 믿습니다 stackoverflow.com/questions/53191739/...
파벨 슬프 폴리아 코프

@PavelPolyakov 나는 보았다. 귀하의 질문에 어떻게 대답해야할지 모르겠습니다. 한동안 JS에서 벗어났습니다. 새로운 정보가 있으면 언제든지 답변을 편집하십시오.
vogdb


2

매개 변수에 특정 특성이있을 것으로 예상되는 경우 추가 @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


0

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

1
@config태그 의 설명서를 가리킬 수 있습니까 ? 내가 발견 usejsdoc.org에 아무것도 하고, 이 페이지는 제안 @config사용되지 않습니다.
Dan Dascalescu

4
내가 생각하는 @config이 시점에서 더 이상 사용되지 않습니다. YUIDoc은 @attribute대신 사용 하는 것이 좋습니다 .
Mike DeSimone
당사 사이트를 사용함과 동시에 당사의 쿠키 정책개인정보 보호정책을 읽고 이해하였음을 인정하는 것으로 간주합니다.
Licensed under cc by-sa 3.0 with attribution required.