jsdoc 사용 안내서(JSDoc 개념, 사용 목적, 사용하기, 태그, 문법, 익스텐션)

🧐 1. jsdoc이란?

JavaScript용 API 문서 생성기입니다.

JSDoc 도구는 소스 코드를 스캔하고 HTML 문서를 생성합니다.

 

즉, JSDoc은 Javascript 문서화 도구로써 소스 파일에 작성된 주석을 파싱하여 모듈, 네임스페이스, 클래스, 메서드, 메서드 매개 변수 등과 같은 항목을 문서화합니다.

 

😤 2. jsdoc의 사용 목적

• JavaScript 애플리케이션 또는 라이브러리의 API를 문서화
• 모듈, 네임스페이스, 클래스, 메서드, 메서드 매개 변수 등과 같은 항목을 문서화
• 함수에 대한 힌트를 커스텀으로 작성 가능
• 코드 유지 보수에 용이

 

✏️ 3. jsdoc 사용하기

• JSDoc 주석은 일반적으로 문서화되는 코드 바로 앞에 위치합니다.
• / + ** + enter키로 사용합니다.
• JSDoc 태그를 사용해서 코드를 설명합니다.

 

🧩 4. jsdoc 태그

1) 블록태그

• 항상 기호(@)로 시작
• 각 블록 태그 뒤에는 줄 바꿈이 와야 합니다(마지막 블록 태그 제외)
• 함수가 허용하는 매개 변수와 같은 코드에 대한 자세한 정보를 제공합니다.
• JSDoc 주석의 최상위 레벨에 있습니다.
• 대부분의 JSDoc 태그
• ex) @param

 

2) 인라인태그

• 일반적으로 HTML 의 앵커 태그 <a> 와 유사하게 설명서의 다른 부분에 연결됩니다.
• 기호(@)로 시작하나, 중괄호 {}로 묶어야 합니다.
• { : 인라인 태그의 시작 } : 인라인 태그의 끝
• 인라인 태그 다음에 줄 바꿈을할 필요가 없습니다.
• 블록 태그 또는 설명의 텍스트 내에 있습니다.
• ex) {@link}

 

💡 5. jsdoc syntax를 사용하는 방법

1) 두 수의 차를 구하는 subtract 함수에 JSDoc 적용하기

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

 

2) 숫자를 인수(argument)로 받아서 문자열로 바꾸는 함수에서 JSDoc으로 인자(parameter)의 유형을 확인하고, 해당 유형이 아닐 시 오류 메시지 보내기

/**
 * Returns a string representation of the given number.
 * @param {number} num - The number to convert to a string.
 * @returns {string} The string representation of the number.
 * @throws {TypeError} If the argument is not a number.
 */
 const numToString = (num) => {
    if (typeof num !== 'number') {
      throw new TypeError('Expected a number');
    }
    return num.toString();
  }

 

🔌 6. 유용한 익스텐션 소개

1) JSDoc Generator

다운로드

 

사용법

-> cmd + shift + p 다음에 Generate JSDoc 선택합니다.

 

 

-> 아래와 같이 param이나 return 등을 자동으로 세팅합니다.

 

2) jsdoc 하이라이트

다운로드

- `something`와 **something**를 활용해서 주석에 하이라이트를 넣을 수 있습니다.

위와 같이 하이라이트를 주면 아래와 같이 호버 시 강조가 됩니다.

(JSDoc 개념, 사용 목적, 사용하기, 태그, 문법, 익스텐션)