JSDoc를 통한 자바스크립트 타입 힌트 제공하기

목차

· JSDoc이란?

· 변수타입

· 함수 타입

· 타입 정의

· CallBack

· DOM

---

시작하기 전에 잠깐의 팁을 가지고 왔는데요, VS Code IDE를 사용하고 있다면, 상단에 @ts-check를 주석으로 추가하면 TypeScript처럼 타입 및 에러 체크를 할 수 있어요 👀

JSDoc이란?

JSDoc은 자바스크립트 API 문서 생성기입니다. 자바스크립트 소스코드에 JSDoc 형식의 주석을 추가하면 API를 설명하는 HTML 문서를 생성할 수 있어요. JSDoc 주석은 일반적인 주석과 다르게 /** */ 로 기술할 수 있어요. 사용 예제를 한번 살펴볼까요? 보통은 JSDoc을 사용할 때 함수 위에 많이 사용을 하고 있지만, 타입스크립트를 아직 도입하지 않은 기업의 경우 타입에 대한 사전적인 정보 제공을 위해 JSDoc을 통해 표현을 하기도 해요.

/** 숫자의 카운트를 올려주는 함수입니다 */
function counter(num) {
	return num++;
}

위에서 타입스크립트를 도입하지 않은 기업의 경우에는 타입에 대한 정의를 JSDoc을 사용하여 관리한다고 했는데, 관련하여 간단한 사용법은 아래와 같이 사용을 할 수 있어요

/** 
* @param {any[]} arr
*/

function compact(arr) {
	if (arr.length > 10) return arr.trim(0, 10);
    // 'any[]' 형식에 'trim' 속성이 없습니다.
}

 변수 타입

/** @type {string} */
let str;

/** @type {number} */
let num;

/** @type {boolean} */ 
let bool;

/** @type {*} */
let any;

/** @type {?} */
let unknown;

/** @type {number[]} */
let nums;

/** @type { {id: number, content: string, completed: boolean} } */
let obj;

/** @type {string{number}} */
let union;

/** @type {Array<{id: number, content: string, completed: boolean }>} */
let generic;

함수 타입

/**
* 두 수의 합을 구하는 함수입니다.
* @type { function(number, number): number) }
*/
const sum = (a: number, b: number) => a + b;

/** 
*	두 수의 곱을 구하는 함수입니다.
*	@type { function(number, numnber): number }
*/
const multiply = (a, b) => a * b;

/** 
*	두 수의 차를 구하는 함수입니다.
*	@param {number} a - the first thing
*	@param {number} b - the second thing
*	@returns {number}
*/
const subtract = (a, b) => a - b;

@param의 경우 타입 구문인 @type과 동일하게 사용할 수 있어요. 단 @param은 매개변수 이름을 추가할 수 있고, 매개변수는 이름을 대괄호로 감싸 선택적 매개변수임을 명시할 수 있어요.

타입 정의

@typedef는 복잡한 타입을 정의할 때 사용이 되어요. 관련하여 아래 예제를 참조해주세요

/** 
*	할일에 대한 타입 정의
*	@typedef (Object} Todo
*	@property {number} id - 할일 id
*	@property {string} content - 할일 내용
*	@property {boolean} completed - 할일 완료 여부
*/

/** 
*	할일 목록에 대한 타입 정의
*	@type {Todo[]]
*/

const todos = [
	{ id: 1, content: 'HTML', complete: false },
    { id: 2, content: 'CSS', complete: true},
    ...
];

CallBack

@callBack은 @typedef와 유사하지만 object 타입 대신 특정한 function 타입을 지정할 수 있어요

// TypeScript Syntax를 사용하는 방법

/**
* @typedef { (data: string, index?: number) => boolean } ExampleTypeFirst
*/

// JSDoc Syntax를 사용하는 방법
/** 
* @callback ExampleTypeTwice
* @param {string} data
* @param {nunmber [index]
* returns {boolean}
*/

/** @type {ExampleTypeFirst} */
const func = s => !(s.length % 2);

DOM

HTML DOM에도 타입스크립트와 동일하게 적용을 할 수 있어요

/** @type {HTMLInputElement} */
const $input = document.querySelector('.foo');

---

레퍼런스

(JavaScript) JSDoc 이란?

 

JSDoc을 사용하여 자바스크립트에 타입 힌트 제공하기 | PoiemaWeb