JSDoc

JSDoc

• 공식 문서
• 문서화를 위해 생겨난 문법
• /** */형태로 작성
• IDE나 문서 자동화 도구가 읽어 자바스크립트를 문서화하는 것이 목적이다.
• 하지만 주석으로 작성하여, 사람이 읽고 이해하는데 도움을 주기도 한다.

📘JSDoc을 주석으로 사용하면 좋은 점

• 제대로 작성하면 typescript처럼 사용할 수 있다
• IDE나 문서 자동화 도구가 읽어 자바스크립트를 문서화해줌
• JSDoc으로 주석을 작성할 경우 해당 함수(메서드)에 마우스를 오버하면 설명을 보여줌

■ VS Code에서의 JSDoc

📘사용방법

■ 정석

태그와 타입을 사용하여 함수의 설명을 작성

/**
 * 함수에 대한 설명
 *
 * @param {타입} a param에 대한 설명
 * @param {타입} b param에 대한 설명
 * @returns {타입} return 값에 대한 설명
 */
function 함수(a, b) {
  // 함수 로직
}

• @param: 함수의 매개변수에 대한 설명
• {타입}: 매개변수의 타입
• @returns: 반환 값에 대한 설명

■ 타입을 작성 X

• 타입을 작성하지 않아도 되지만 IDE나 문서 자동화 도구가 이해할 수 없을 수도 있음

/**
 * 함수에 대한 설명
 *
 * @param a param에 대한 설명
 * @param b param에 대한 설명
 * @returns return 값에 대한 설명
 */
function 함수(a, b) {
  // 함수 로직
}

■ 태그 X

• 다른 사람의 이해를 목적으로 주석으로만 사용할 수 있음

/**
 * 함수에 대한 설명
 * 함수에 대한 설명2
 */
function 함수(a, b) {
  // 함수 로직
}

📘사용 예 - 클래스

/**
 * @class
 * @classdesc 사람을 나타내는 클래스입니다.
 */
class Person {
  /**
   * @constructor
   * @param {string} name - 사람의 이름입니다.
   */
  constructor(name) {
    this.name = name;
  }

  /**
   * 사람의 이름을 반환합니다.
   * @returns {string} 사람의 이름
   */
  getName() {
    return this.name;
  }
}

📘사용 예 - svelte

svelte github source

/**
 * @type {Array<import('./private').SubscribeInvalidateTuple<any> | any>}
 */
const subscriber_queue = [];

/**
 * Creates a `Readable` store that allows reading by subscription.
 *
 * https://svelte.dev/docs/svelte-store#readable
 * @template T
 * @param {T} [value] initial value
 * @param {import('./public').StartStopNotifier<T>} [start]
 * @returns {import('./public').Readable<T>}
 */
export function readable(value, start) {
  return {
    subscribe: writable(value, start).subscribe
  };
}