JSDoc 사용법 타입 정의하기 typedef params 비동기함수

JSDoc 이란?

JSDoc을 자바스크립트 프로그램이나, API를 문서화하기 위한 스타일 도구입니다.

기본적으로 /** 을 작성하면 JSDoc Parser가 인식을 합니다. 별 한 개 또는 세 개는 인식을 하지 않습니다.

다양한 태그를 이용해서 정보를 저장할 수 있고, 문서화할 수 있습니다.

/**
 * 두개 숫자 더하기 
*/
function add(num1, num2) {
   return num1 + num2
}

 

JSDoc 장점

단순히 설명을 작성하는 것 외에도 장점이 있습니다.

 

1. JSDoc 목적에 맞게 문서화를 할 수 있고,
2. 타입을 미리 정의하기 때문에 IDE 자동 완성 기능을 사용할 수 있습니다.
3. 생산성 향상과 오류 찾는 디버깅 시간을 줄일 수 있습니다.

자바스크립트 프로젝트에서 타입스크립트를 도입하기 어려울 때, 사용할 수 있습니다.

다만, 타입이 달라서 오류가 나지 않고 강제성은 없습니다.

JSDoc 사용법

태그 앞에 @를 붙여서 사용합니다.

@param

타입, 변수 이름, 설명을 작성할 수 있습니다.

/**
  * @param {number} num1 - 첫번째 숫자
  * @param {number} num2 - 두번째 숫자
  */
  function add(num1, num2) {
    return num1 + num2
  }

@returns

타입과 설명을 작성할 수 있습니다.

/**
  * @param {number} num1 - 첫번째 숫자
  * @param {number} num2 - 두번째 숫자
  * @returns {number} 두개 숫자 더한 결과값
*/
function add(num1, num2) {
   return num1 + num2
}

@typedef

사용자 정의 타입을 만들 수 있습니다.

정의한 타입을 사용할 수 있습니다.

/**
  * @typedef UserInfo
  * @property {string} name
  * @property {number} age
  * @property {string} address
  */

 

비동기 함수 JSDoc 작성하기

비동기 함수는 @async 태그를 이용해서 비동기 함수로 나타낼 수 있습니다.

아래 함수는 user 정보를 가져오는 비동기 함수입니다.

returns 태그에 Promise를 작성하고 위에서 사용자 정의한 UserInfo를 작성하였습니다.

 

백엔드에서 정의한 타입을 작성하면, 화면에 렌더링 할 때 타입을 확인하고 사용할 수 있는 장점이 있습니다.

/**
  * @async
  * @returns {Promise<UserInfo>}
  */
function getUserInfo() {
  // async code
  return new Promise((resolve) => {
     resolve({ name: 'superman', age: 30, address: '서울시' })
   })
}

 

그 외에도 많은 태그가 있습니다.

아래 사이트에서 확인할 수 있습니다.

Use JSDoc: Index