[Javascript] JSDoc

References

https://okayoon.tistory.com/entry/JSDoc를-사용해서-Javasript-문서화해보자

 

개요

JSDoc은 자바스크립트 파일(js 확장자) 소스코드에 @기호를 이용하여 주석 및 타입 설정을 할 수 있는 마크업 언어 패키지이다.

 

설치

현재 프로젝트 디렉토리를 확인 후 다음과 같이 작업한다.

// 일반적인 설치
npm i --save-dev jsdoc

// 테마를 이용한 설치
npm i docdash

이 후, jsdoc.conf파일을 확인 후 필요시 변경한다.

 

문서설명

@author

작성자 식별, 이메일 주소를 기재

// @author <name>
// @author <name> [<emailAddress>]

@version

사용하는 라이브러리 버전 표기

// *@version 버전정보*

@copyright

저작권 정보 표기

// @copyright <some copyright text>

@file (@fileoverview, @overview)

파일에 대한 설명

// @file <some text>

@license

라이센스에 대한 정보 표기

// @license <identifier>

 

함수 사용

@this

해당 함수내부의 this가 참조하는 것을 표시

// @this <namePath>

@constant (@const)

상수를 표시

// @constant [<type> <name>]

@description (@desc)

설명을 표시

// @description <some description>

@throws (@exception)

메소드에 의해 발생된 오류나 예외사항을 표시

// @throws free-form description
// @throws {<type>}
// @throws {<type>} free-form description

@param (@arg, @argument)

함수에 전달받은 인자 값의 이름 유형 및 설명 표시

*// @param  <someParamName>
// @param {<type>} <someParamName>
// @param {<type>} <some description>*

@requires

필요한 모듈이 있음을 표현

// @requires <someModuleName>

@callback

콜백으로 받은 인자 및 반환 값에 대한 정보 제공

// @callback <namepath>

@todo

해야하거나, 완료해야할 작업이 필요할때 표시

// @todo text describing thing to do.

@return (@returns)

함수가 반환하는 값을 표시

// @returns [{type}] [description]

@see

연관성 있는 문서나 리소스 참조함을 표시

// @see <namepath>
// @see <text>

@link ({@linkcode}, {@linkplain})

namepath 또는 url에 대한 링크 생성

// {@link namepathOrURL}
// [link text]{@link namepathOrURL}
// {@link namepathOrURL|link text}
// {@link namepathOrURL link text (after the first space)}

@since

클래스, 메서드 등이 특정 버전에서 추가되었을때 사용

// @since <versionDescription>

 

이벤트

@fires (@emits)

메소드 호출시 지정된 유형의 이벤트 발생 표현

// @fires <className>#<eventName>
// @fires <className>#[event:]<eventName>

@event

특정 이벤트를 정의

*// @event <className>#<eventName>
// @event <className>#[event:]<eventName>*

@listens

지정된 이벤트를 수신하는 것을 표현

// @listens <eventName>

@example

예제 제공

// @example 
// @example <caption>captionText</caption>

@global

전역함수 표현, 로컬에 작성되고 전역에 할당된 태그 사용시 유용

(function() {
  // @global
  var foo = 'hello foo';
  this.foo = foo;
}).apply(window);

@namespace

네임스페이스 프로그래밍 시 객체 표현

// @namespace [[{<type>}] <SomeName>]

@inner

네임스페이스 태그의 부모-자녀 참조

/** @namespace */
var MyNamespace = {
  /**
   * foo is now MyNamespace~foo rather than MyNamespace.foo.
   * @inner
   */
  foo: 1
};

@alias

네임스페이스 태그의 멤버 참조처리

/** @namespace */
var Apple = {};(function(ns) {

  /**
   * @namespace
   * @alias Apple.Core
   */
  var core = {}; 

  /** Documented as Apple.Core.seed */
  core.seed = function() {}; 
  ns.Core = core;

})(Apple);

 

클래스

@class (@constructor)

함수 생성자

// @class [<type> <name>]

@classdesc

함수 생성자 설명

// @classdesc <some description>

@constructs

객체 리터럴을 사용하여 클래스를 정의했을때 해당 멤버 표시

// @constructs [<name>]

@lends

함수 생성자의 멤버

// @lends <namepath>

@abstract (@virtual)

상속하는 객체에서 재정의 하는 멤버 식별(오버라이딩)

/**
 * Generic dairy product.
 * @constructor
 */
function DairyProduct() {}

/**
 * Check whether the dairy product is solid at room temperature.
 * @abstract
 * @return {boolean}
 */
DairyProduct.prototype.isSolid = function() {
	throw new Error('must be implemented by subclass!');
};

/**
 * Cool, refreshing milk.
 * @constructor
 * @augments DairyProduct
 */
function Milk() {}

/**
 * Check whether milk is solid at room temperature.
 * @return {boolean} Always returns false.
 */
Milk.prototype.isSolid = function() {
	return false;
};

@augments (@extends)

클래스 기반이나 프로토타입 기반에서 상속을 나타내고 상위 객체를 추가

// @augments <namepath>