jsdoc3 커스텀(Customized) 기능 사용 설명

1.Grouping

관련 태그

@group

개요

관련 모듈이나 컴포넌트를 명시한 그룹 단위로 묶어서 보여주는 기능

그림. Polyfill 과 EvergreenJs 그룹으로 그루핑한 화면

사용법

JSDOC 주석 중 class 정의부나 namespace 정의부에 group 태그를 사용하여 "그룹이름"을 명시한다. @group 그룹이름

그러면 동일한 그룹이름을 갖는 컴포넌트들끼리 그룹핑 된다. @group 미지정 시 global 이라는 그룹이름을 갖는다.

사용예

Class 에 그룹을 지정한 예

/**
 *
 * Class
 * The Class() object is used to implement the application using object-oriented programming.
 * @group EvergreenJs
 * @ko Class는 어플리케이션을 객체지향 프로그래밍 방식으로 구현하는데 사용합니다.
 * @class
 * @name eg.Class
 * @param {Object} oDef Class definition of object literal type. <ko>리터럴 형태의 클래스 정의부</ko>
 */

Function Polyfill 에 그룹을 지정한 예

/**
 * @namespace Function
 * @group Polyfill
 */

주의사항

Class 컴포넌트가 아닌 경우 namespace 지정 영역에 group 이름을 지정한다.

namespace 의 함수 (eg. Function.prototype.bind) 에 group 을 지정하지 않도록 주의한다.

TODO

1. 지정된 그룹이 없는 경우 group 표기를 하지 않는다.

2. 파라미터 한글 표기

관련 태그

<ko>...</ko>

개요

주석 작성 시 영문 작성을 기본으로 하였기 때문에 한글 표기를 위한 방안이다.

사용법

파라미터 설명 옆에 <ko>한글 설명</ko> 태그를 두어 한글 설명을 추가한다.

사용예

@param {Object} oDef Class definition of object literal type. <ko>리터럴 형태의 클래스 정의부</ko>

3. Codepen 코드 삽입

관련 태그

@codepen

개요

예제 코드와 예제 결과를 웹 브라우저에서 바로 보고 확인할 수 있는 도구로 Codepen 을 도입함에 따라 Codepen 의 예제를 jsdoc 문서에 바로 embed 할 수 있는 기능을 제공한다. 이를 통해 관련 예제들을 문서에서 한번에 확인할 수 있는 편의를 제공한다.

주요 기능

• codepen 코드 삽입 (클래스, 메소드, 네임스페이스 각각 1개까지 지정 가능, 메소드가 10개이면 10개 지정 가능)
• codepen collectio 링크 삽입 (클래스, 메소드, 네임스페이스 각각 1개까지 지정 가능, 메소드가 10개이면 10개 지정 가능)

사용법

codepen 을 삽입하고자 하는 위치에 아래와 같은 태그를 지정한다.

@codepen {
    "id":"임베드 할 대표 codepen id", /* 미지정 시 code embed 하지 않음 */
    "ko":"임베드 시 상단에 표시될 한글 표기",
    "en":"English title when embedding a codepen.",
    "collectionId":"링크를 삽입할 Collection ID", /* 미지정 시 collection URL 링크를 삽입하지 않음 */
    "height" : 컨텐트에 사이즈에 맞게 높이 값 /* 너비는 항상 최대, default: 268 */
}

부가설명

id 는 codepen 각 컨텐츠 별 URL(eg. http://codepen.io/evergreenjs/pen/rVOpPK)에서 .../pen/ 뒤에 있는 영문자(eg.rVOpPK) 를 입력한다. collectionId 에는 codepen 컬렉션 URL (eg. http://codepen.io/collection/ArxyLK/) 중 .../collection/ 뒤에 있는 영문자(eg.ArxyLK)를 입력한다.

사용예

@codepen {"id":"rVOpPK", "ko":"플리킹 기본 예제", "en":"Flicking default example", "collectionId":"ArxyLK", "height" : 403}

4. hooks 카테고리 추가

관련 태그

@hook

개요

cssHooks(css) 및 transform(animate) 관련 hook 이 추가됨에 따라 jQuery Extentions 내 hook 에 대한 필요성으로 태그를 제공한다.

사용법

다음과 같이 주석에 @hook 태그를 추가한다.

/**
 * Apply css prefix cssHooks
 * 
 * @name jQuery#cssPrefix
 * @hook
 */

JSDOC 주석 중 @hook 이라는 태그를 추가함에 jQuery Extentions 에 hook 카테고리로 적용된다.

결과

위 태그 추가를 통해 다음과 같은 결과를 확인할 수 있다.