JSDoc으로 타입 힌트 제공하면서 주석 예쁘게 달기

4 분 소요

✔️ JSDoc 이란?

JSDoc은 자바스크립트 API 문서 생성기인데요. VSCode나 Webstorm 같은 편집기에서 기본으로 제공하고 있는 기능입니다. 이 기능을 사용하면 주석을 예쁘게 만들 수 있을 뿐만 아니라 함수 정보, 타입 힌트 등을 제공할 수 있어서 유용합니다.

✔️ JSDoc 사용법

사용법은 간단합니다. 아래와 같이 입력하면 됩니다.

/** ... */

기본 형태가 위와 같기 때문에 각 주석은 반드시 /** ... */ 사이에 기술해야 합니다. 만약 /*, /*** 와 같이 시작하게 된다면 그것은 무시됩니다.

/**
 * 이름과 나이 입력받아 출력하는 함수
 * @param {string} name 이름 입력란 입니다!
 * @param {number} age 나이 입력란 입니다!
 * @returns 이름과 나이를 출력합니다~
 */
const lime = (name, age) => {
  return name + age;
};

예를 들면 위와 같이 사용될 수 있습니다. 주석 설명은 자주 사용할만한 것들로 정리해놓았으니 아래를 참고해주세요. 추가로 더 자세한 내용이 궁금하시다면 참고사이트에 있는 JSDoc 문서를 참고해주세요 :)

✔️ 주석설명

👉 문서 주석

`@version`

라이브러리 버전 정보를 나타냅니다.

/**
 * Solves equations of the form a * x = b. Returns the value
 * of x.
 * @version 1.2.3
 * @tutorial solver
 */
function solver(a, b) {
  return b / a;
}

`@file (@fileoverview, @overview)`

파일 정보를 나타냅니다.

`@copyright`

저작권 정보를 나타냅니다.

/**
 * @file This is my cool script.
 * @copyright Michael Mathews 2011
 */

`@license`

소프트웨어 라이센스 정보를 나타냅니다.

/**
 * Utility functions for the foo package.
 * @module foo/util
 * @license Apache-2.0
 */

`@author`

작성자 정보를 나타냅니다. 이메일 주소를 입력하는 경우에는 <> 를 활용하면 됩니다.

/**
 * @author Jane Smith <jsmith@example.com>
 */
function MyClass() {}

👉 함수 주석

`@this`

this 키워드가 참조하는 정보를 나타냅니다.

/** @constructor */
function Greeter(name) {
  setName.apply(this, name);
}

/** @this Greeter */
function setName(name) {
  /** document me */
  this.name = name;
}

`@constant (@const)`

상수 정보를 나타냅니다.

/** @constant
    @type {string}
    @default
*/
const RED = "FF0000";

/** @constant {number} */
var ONE = 1;

`@description`

설명 정보를 나타냅니다.

/**
 * @param {number} a
 * @param {number} b
 * @returns {number}
 * @description Add two numbers.
 */
function add(a, b) {
  return a + b;
}

만약 첫 번째 줄인 경우 아래처럼 생략하여 쓸 수 있습니다.

/**
 * Add two numbers.
 * @param {number} a
 * @param {number} b
 * @returns {number}
 */
function add(a, b) {
  return a + b;
}

`@throws (@exception)`

오류나 예외사항을 나타냅니다.

/**
 * @throws {InvalidArgumentException}
 */
function foo(x) {}

/**
 * @throws Will throw an error if the argument is null.
 */
function bar(x) {}

/**
 * @throws {DivideByZero} Argument x must be non-zero.
 */
function baz(x) {}

`@param (@arg, @argument)``

파라미터 정보를 나타냅니다.

/**
 * @param {string} somebody Somebody's name.
 */
function sayHello(somebody) {
  alert("Hello " + somebody);
}

`@callback`

콜백으로 받은 인자 및 반환값에 대한 정보를 나타냅니다.

클래스별

/**
 * @class
 */
function Requester() {}

/**
 * Send a request.
 * @param {Requester~requestCallback} cb - The callback that handles the response.
 */
Requester.prototype.send = function (cb) {
  // code
};

/**
 * This callback is displayed as part of the Requester class.
 * @callback Requester~requestCallback
 * @param {number} responseCode
 * @param {string} responseMessage
 */

글로벌

/**
 * @class
 */
function Requester() {}

/**
 * Send a request.
 * @param {requestCallback} cb - The callback that handles the response.
 */
Requester.prototype.send = function (cb) {
  // code
};

/**
 * This callback is displayed as a global member.
 * @callback requestCallback
 * @param {number} responseCode
 * @param {string} responseMessage
 */

`@requires`

필요한 모듈이 있음을 나타냅니다.

/**
 * This class requires the modules {@link module:xyzcorp/helper} and
 * {@link module:xyzcorp/helper.ShinyWidget#polish}.
 * @class
 * @requires module:xyzcorp/helper
 * @requires xyzcorp/helper.ShinyWidget#polish
 */
function Widgetizer() {}

`@todo`

해야할 일이나 작업에 대한 정보를 나타냅니다.

/**
 * @todo Write the documentation.
 * @todo Implement this function.
 */
function foo() {
  // write me
}

`@return (@returns)`

리턴값을 나타냅니다.

/**
 * Returns the sum of a and b
 * @param {number} a
 * @param {number} b
 * @returns {number}
 */
function sum(a, b) {
  return a + b;
}

`@since`

클래스나 메소드 등이 특정 버전에서 추가되었을 경우 사용합니다.

/**
 * Provides access to user information.
 * @since 1.0.1
 */
function UserRecord() {}

✔️ 참고사이트

https://jsdoc.app/

🔔포스팅 공지
개인 공부 기록용 블로그 입니다.
잘못된 부분이 있을 시 메일이나 댓글로 지적해주시면 감사드리겠습니다 :)

Twitter Facebook LinkedIn

LIME