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

Program / 글쓴이

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

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

답변

이것이 문서에 설명 된대로 의도 된 방식 입니다.

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

답변

나는 개인적으로 이것을 사용합니다.

/**
* @param {{
  a: number
  b: number
}} param0
* @returns {number} The sum
*/
const func = ({ a, b }) => a + b;

바로 거기에 개체를 만듭니다.

또한 타이프 라이터를 활용 하고, obtional 선언 할 것 b같은 b?나 b: number | undefined같은 JSDoc도 조합 할 수 있습니다

답변

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

답변