JSDoc에서 구조화 된 함수 매개 변수 문서화


89

이전에는 항상 다음과 같이 개체 매개 변수를 문서화했습니다.

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

그러나 해체 된 함수 매개 변수를 사용하는 가장 좋은 방법이 무엇인지 잘 모르겠습니다. 객체를 무시하고 어떻게 든 정의하거나 문서화하는 가장 좋은 방법은 무엇입니까?

/**
 * 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에서 나는 (파괴 후) 매개 변수를 설명하고 분해를 무시하면 드물게 발생하는 경우를 제외하고 대부분 작동한다는 것을 발견했습니다. 따라서 귀하의 예에서 두 개의 매개 변수 foobar. 최종 솔루션은 아니지만 객체를 사용하는 모든 접근 방식에서 검사 오류가 발생했으며 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;

.NET과 같은 여러 개의 비 구조화 된 인수가있을 때 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})-요점은 JSDoc @param태그가 순서가없는 AFAIK이고 키가 JSDoc이 속성 이름을 사용하여 일치하려고 할 때 모호 할 수 있다는 것입니다. 다음 버전의 VSCode에서는 위치 조회를 사용하여이 시나리오를 해결할 것입니다.
ZachB

1
감사합니다, @ d0gb3r7. 답변의 링크를 업데이트했습니다.
Cerbrus


-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 2016-06-11

실제로 그의 예제 바로 뒤에 동일한 링크가 .NET에 대해 동일한 jsdoc 주석이있는 상대 예제를 제공합니다 Project.prototype.assign = function({ name, department }). 예 전에 그들은 "매개 변수가 명시적인 이름없이 구조화되면 개체에 적절한 이름을 지정하고 해당 속성을 문서화 할 수 있습니다."라고 말합니다.
notacouch
당사 사이트를 사용함과 동시에 당사의 쿠키 정책개인정보 보호정책을 읽고 이해하였음을 인정하는 것으로 간주합니다.
Licensed under cc by-sa 3.0 with attribution required.