JSDoc
JSDoc은 개발자가 작성한JavaScript코드의 API를 설명하는 마크업 언어
JSDoc은 JavaScript API 문서 생성기이며, 주석을 통해 함수의 정보, 타입 힌트 등 코드의 부가적인 설명을 제공할 수 있는 기능이다.
주로 VSCode, Webstorm...등등 코드 에디터에서 기본으로 제공하고 있다.
JSDoc의 기본 형태는 다음과 같으며, 각 주석은 반드시 /* * ... */ 사이에 기술해야 한다.
/**
* 문자열을 출력하는 함수
* @param {*} text 매개변수 text
* @returns text를 출력
*/
const hello = (text) => {
console.log(text);
};
hello('Hello');
이외에도 다음과 같은 주석을 사용할 수 있다.
Document
@version
version은 라이브러리의 버전 정보를 나타낸다.
/**
* 문자열을 출력하는 함수
* @version 1.2.3
*/
const hello = (text) => {
console.log(text);
};
hello('Hello');@copyright
copyright는 파일 개요, 설명에 대한 저작권 정보를 나타낸다.
/**
* @file This is my cool script.
* @copyright Michael Mathews 2011
*/@file
file은 파일의 정보를 나타낸다.
/**
* @file This is my cool script.
* @copyright Michael Mathews 2011
*/@license
license는 소프트웨어의 라이센스 정보를 나타낸다.
/**
* Utility functions for the foo package.
* @module foo/util
* @license Apache-2.0
*/@author
author는 작성자 정보를 나타내며, <>를 활용하여 이메일 주소를 입력할 수 있다.
/**
* @author mirrer <mirrer@naver.com>
*/
const hello() => {}Function
@this
this는 해당 함수내부의 this가 참조하는 것을 표시한다.
/** @constructor */
function Greeter(name) {
setName.apply(this, name);
}
/** @this Greeter */
function setName(name) {
/** document me */
this.name = name;
}@constant
constant는 상수 정보를 나타낸다.
/** @constant
@type {string}
@default
*/
const RED = "FF0000";
/** @constant {number} */
let ONE = 1;@descript
descript은 설명 정보를 나타낸다.
/**
* @param {number} a
* @param {number} b
* @returns {number}
* @description Add two numbers.
*/
function add(a, b) {
return a + b;
}만약 descript이 첫 번째 줄에 위치하는 경우에는 다음과 같이 생략이 가능하다.
/**
* Add two numbers.
* @param {number} a
* @param {number} b
* @returns {number}
*/
function add(a, b) {
return a + b;
}@throws
throws는 메소드에 의해 발생된 오류나 예외사항을 표시한다.
/**
* @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
param는 함수에 전달받은 인자 값의 이름, 유형, 설명...등을 나타낸다.
/**
* @param {string} name Somebody's name.
*/
const sayHello => (name) {
console.log("Hello " + name);
}@callback
callback은 콜백으로 받은 인자 및 반환값에 대한 정보를 나타내며, 아래와 같이 클래스 또는 글로벌로 나타낼 수 있다.
- Class
/**
* @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
*/- Global
/**
* @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
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
*/
const Widgetizer => () {};@todo
todo는 해야할 일이나 작업에 대한 정보를 나타낸다.
/**
* @todo Write the documentation.
* @todo Implement this function.
*/
const foo => () {
// write me
}@return
return은 리턴값을 나타낸다.
/**
* Returns the sum of a and b
* @param {number} a
* @param {number} b
* @returns {number}
*/
const sum = (a, b) => {
return a + b;
}@since
since는 클래스, 메서드 등이 특정 버전에서 추가되었을때 사용한다.
/**
* Provides access to user information.
* @since 1.0.1
*/
const UserRecord = () => {};참고 자료
