[Javascript] JSDoc

코딩 애플 유튜브 영상을 보던 중 몰랐던 주석 작성 방법이 있어 기록해두고자 한다.

 

[해당 유튜브 영상]

 

---

이제껏 나는 js에서 주석 작성 시 vscode 단축키인 Ctrl + / 를 통해 주석을 작성했다.

// 주석

 

그런데 코딩애플이 소개해주는 주석 방식은 매우 유용한 기능을 제공한다.

 

1. JSDoc

(1) 작성 방법

주석 작성 방법은 아래와 같다.

/** 주석 /

 

예를 들기 위해 아래와 같이 함수 위에 해당 함수에 대한 설명 주석을 작성하면

/** 햄버거 버튼 클릭 시 실행  */
function onClickHamBtn(e){
    e.preventDefault();
    navi.classList.toggle('active');
    header.classList.toggle('active');
}

onClickHamBtn();

아래와 같이 함수 호출 시 마우스를 함수에 올리면 해당 설명 주석이 뜨게 되며 우리는 이 함수에 대해 복기하고 힌트를 얻을 수 있게 된다.

 

(2) Type 명시

더 구체적인 설명을 위해 파라미터를 받는 함수를 생성하고 이 함수 위에 /**를 작성하고 엔터를 쳐보자.

 

그럼 아래와 같이 파라미터에 대한 주석도 작성할 수 있게 된다.

/**
 * 
 * @param name 
 * @param age 
 * @returns 
 */
function Hello(name, age) {
    return name + age
}

 

각 파라미터에 대한 주석과 권장하는 파라미터 Type을 작성하고 

/**
 * 
 * @param {string} name 사람 이름
 * @param {number} age 사람 나이
 * @returns 두개를 합쳐서 문자로 return
 */
function Hello(name, age) {
    return name + age
}

 

아까와 같이 함수 호출 시 함수에 마우스를 올리면 우리가 파라미터에 대해 작성한 주석도 보여지게 된다.

 

이렇게 Type을 명시해줬을 때 보는 사람에게 힌트가 된다는 것 외에도 좋은 점이 있는데 각 파라미터에 대한 Type 정보를 컴퓨터에게 알려줬기에 각 파라미터에 맞는 자동완성도 가능해진다.

 

(3) @version / @see

이 외에도 추가적으로 작성할 수 있는 정보가 있는데

라이브러리를 사용할 경우 해당 라이브러리의 버전 정보나 참고 자료 url 첨부까지 가능하다.

/**
 * 
 * @param {string} name 사람 이름
 * @param {number} age 사람 나이
 * @returns 두개를 합쳐서 문자로 return
 * @version 1.3.1
 * @see https://www.youtube.com/watch?v=ORmnc-hLrYs&list=PLlxKkQWUbQMeFOwNl69MtnC1ZDmNSxeyP&index=1
 */
function Hello(name, age) {
    return name + age
}

 

(4) @readonly

readonly를 작성하면 강제성은 없지만 보는 사람에게 이 부분은 수정하지 말라는 메시지도 전달할 수 있다.

/**
 * @readonly
 */

 

(5) @todo

todo 작성도 가능하여 해당 기능에 대해 부가적으로 더 진행해야 할 내용에 대해서도 작성해둘 수 있다.

/**
 * @todo 내일까지 기능 구현
 */

 

(6) @deprecated

해당 함수를 사용하지 말라는 의미로 deprecated를 사용할 수 있는데 이럴 경우 해당 함수를 사용하면 줄이 그어지게 된다.

/**
 * @deprecated 이거 말고 다른 함수 쓰세요
 */

 

2. JSDoc vs Typescript

그럼 의문이 들 수도 있다. Type 명시같은 경우에는 Typescript 써도 되는 게 아닌가?

 

맞는 말이다. 그러나 Typesciprt가 아닌 JSDoc을 사용하는 사람들의 의견으로는

1. Typescript의 기준이 너무 엄하고
2. ts 파일에서 js 파일로 변환 시 파일도 무거워지기 때문이라고 한다.

 

그저 프로젝트의 상황과 특성에 맞게 적절한 방식을 택하면 될 것 같다.