맨위로가기

JSDoc

"오늘의AI위키"는 AI 기술로 일관성 있고 체계적인 최신 지식을 제공하는 혁신 플랫폼입니다.
"오늘의AI위키"의 AI를 통해 더욱 풍부하고 폭넓은 지식 경험을 누리세요.
목차

1. 개요

JSDoc은 자바스크립트 코드를 문서화하기 위한 도구로, 자바의 Javadoc과 유사한 문법을 사용하지만 자바스크립트의 동적 특성을 처리하도록 특화되었다. 1999년 넷스케이프/모질라 프로젝트에서 처음 등장했으며, 이후 여러 번의 개편을 거쳐 현재 Node.js에서 실행되는 JSDoc 3.0 버전이 사용되고 있다. JSDoc은 `@author`, `@param`, `@returns` 등 다양한 태그를 제공하여 코드의 기능, 매개변수, 반환 값 등을 문서화하며, Closure Compiler, TypeScript 등에서 활용되어 코드 최적화 및 타입 검사에 사용된다. 또한, Sublime Text, IntelliJ IDEA, Visual Studio Code 등 다양한 편집기 및 IDE에서 JSDoc을 지원하여 개발 편의성을 높인다.

더 읽어볼만한 페이지

  • 자유 문서 생성기 - Doxygen
    Doxygen은 소스 코드 주석에서 문서를 추출하여 다양한 형식으로 결과물을 생성하는 도구로, 여러 프로그래밍 언어와 운영체제를 지원하며 다이어그램 생성 및 수식 표현 기능도 제공한다.
  • 자유 문서 생성기 - CWEB
    CWEB은 내용 분석이 불가능한 위키백과 문서이며, 정보의 투명성과 접근성 개선이 필요한 상황이다.
  • 자바스크립트 프로그래밍 도구 - 파이어버그 (소프트웨어)
    2005년 조 휴이트가 개발한 파이어버그는 웹 개발 생산성 향상에 기여한 파이어폭스 확장 기능 기반의 오픈 소스 웹 개발 도구였으나, 파이어폭스 개발자 도구에 기능이 통합되며 더 이상 사용이 불가능해졌다.
  • 자바스크립트 프로그래밍 도구 - 그런트
    그런트는 자바스크립트 기반의 작업 실행 도구로, package.json과 Gruntfile을 통해 프로젝트를 구성하고 다양한 플러그인을 활용하여 작업 확장이 용이한 프로젝트 자동화 도구이다.
JSDoc - [IT 관련 정보]에 관한 문서

2. 역사

JSDoc은 Javadoc과 유사하게 자바 코드를 문서화하는 데 사용되지만, 동적인 JavaScript 동작을 처리하도록 특화되었다는 차이점이 있다.[4]

1999년 넷스케이프(Netscape)/모질라(Mozilla) 프로젝트 Rhino에서 Javadoc과 유사한 문법을 사용해 자바스크립트를 문서화한 초기 예시가 공개되었으며, 이는 Java로 작성된 자바스크립트 런타임 시스템이다.[1]

micmath(Michael Mathews)는 JSDoc의 모든 주요 버전을 이끌었다. 2001년 Perl로 작성된 JSDoc.pm을 시작으로, 2007년 JSDoc 1.0, 2008년 JSDoc 2.0 ("jsdoc-toolkit")을 거쳐, 2011년 JSDoc 3.0으로 발전시켰다. JSDoc 3.0은 GitHub에 호스팅되었고, Node.js에서 실행된다.[4]

2. 1. 초기 역사

JSDoc의 문법과 의미는 자바(Java)로 작성된 코드를 문서화하는 데 사용되는 Javadoc 체계와 유사하다. JSDoc은 JavaScript의 동적인 동작을 처리하도록 특화되어 있다는 점에서 Javadoc과 다르다.[4]

자바스크립트를 문서화하기 위해 Javadoc과 유사한 문법을 사용한 초기 예시는 1999년 넷스케이프(Netscape)/모질라(Mozilla) 프로젝트 Rhino와 함께 공개되었다. 이는 Java로 작성된 자바스크립트 런타임 시스템이다.[1] 이 프로젝트는 자바스크립트 기능을 보여주는 예시로 1.3 버전까지의 "JSDoc" HTML 생성기를 포함했다.[1]

"JSDoc"의 모든 주요 버전은 micmath(Michael Mathews)가 이끌었다. 그는 2001년 Perl로 작성된 간단한 시스템인 JSDoc.pm으로 시작했다. 이후 캐나다 프로그래머 Gabriel Reid의 기여를 받았다. 이 시스템은 CVS 저장소에서 SourceForge에 호스팅되었다.[2] JSDoc 1.0 (2007)에서 그는 (다시 Rhino를 위해) JavaScript로 시스템을 다시 작성했고, 일련의 확장을 거쳐 JSDoc 2.0 (2008)은 "jsdoc-toolkit"이라는 이름을 얻었다. MIT 라이선스 하에 출시되었으며, Subversion 저장소에서 Google Code에 호스팅되었다.[3] 2011년까지 그는 시스템을 JSDoc 3.0으로 리팩토링하고 결과를 GitHub에 호스팅했다. 현재 Node.js에서 실행된다.[4]

2. 2. 발전 과정

JSDoc의 문법과 의미는 자바로 작성된 코드를 문서화하는 데 사용되는 Javadoc 체계와 유사하다. JSDoc은 JavaScript의 동적인 동작을 처리하도록 특화되어 있다는 점에서 Javadoc과 다르다.[4]

자바스크립트를 문서화하기 위해 Javadoc과 유사한 문법을 사용한 초기 예시는 1999년 넷스케이프(Netscape)/모질라(Mozilla) 프로젝트 Rhino와 함께 공개되었다. 이는 Java로 작성된 자바스크립트 런타임 시스템이다.[1] 이 프로젝트는 자바스크립트 기능을 보여주는 예시로 1.3 버전까지의 "JSDoc" HTML 생성기를 포함했다.[1]

"JSDoc"의 모든 주요 버전은 micmath(Michael Mathews)가 이끌었다. 그는 2001년 Perl로 작성된 간단한 시스템인 JSDoc.pm으로 시작했다. 이후 캐나다 프로그래머 Gabriel Reid의 기여를 받았다. 이 시스템은 CVS 저장소에서 SourceForge에 호스팅되었다.[2] JSDoc 1.0 (2007)에서 그는 (다시 Rhino를 위해) JavaScript로 시스템을 다시 작성했고, 일련의 확장을 거쳐 JSDoc 2.0 (2008)은 "jsdoc-toolkit"이라는 이름을 얻었다. MIT 라이선스 하에 출시되었으며, Subversion 저장소에서 Google Code에 호스팅되었다.[3] 2011년까지 그는 시스템을 JSDoc 3.0으로 리팩토링하고 결과를 GitHub에 호스팅했다. 현재 Node.js에서 실행된다.[4]

3. JSDoc 태그

JSDoc은 자바스크립트 코드에 주석을 달아 API 문서를 생성하는 데 사용되는 마크업 언어이다. 코드 예시와 함께 JSDoc에서 사용되는 몇 가지 주요 태그들을 살펴보자.

```javascript

/** @class 원을 나타내는 Circle 클래스. */

class Circle {

/**


  • Circle 인스턴스를 생성한다.

  • @author moi
  • @param {number} r 원의 반지름.
  • /

constructor(r) {

/** @private */ this.radius = r

/** @private */ this.circumference = 2 * Math.PI * r

}

/**

  • 지름으로부터 새로운 Circle을 생성한다.

  • @param {number} d 원의 지름.
  • @return {Circle} 새로운 Circle 객체.
  • /

static fromDiameter(d) {

return new Circle(d / 2)

}

/**

  • 원의 둘레를 계산한다.

  • @deprecated 1.1.0 버전부터 사용 중단됨; getCircumference를 대신 사용
  • @return {number} 원의 둘레.
  • /

calculateCircumference() {

return 2 * Math.PI * this.radius

}

/**

  • 미리 계산된 원의 둘레를 반환한다.

  • @return {number} 원의 둘레.
  • @since 1.1.0
  • /

getCircumference() {

return this.circumference

}

/**

  • Circle 객체의 문자열 표현을 찾는다.

  • @override
  • @return {string} 사람이 읽을 수 있는 형태의 Circle 객체 표현.
  • /

toString() {

return `[반지름이 ${this.radius}인 Circle 객체]`

}

}

/**

  • 원을 출력한다.

  • @param {Circle} circle
  • /

function printCircle(circle) {

/** @this {Circle} */

function bound() {

console.log(this)

}

bound.apply(circle)

}

```

위 코드는 `@class`, `@author`, `@param`, `@private`, `@return`, `@deprecated`, `@since`, `@override`, `@this` 등 다양한 JSDoc 태그를 사용하는 방법을 보여준다. 이 태그들은 코드의 각 부분이 어떤 역할을 하는지, 어떤 매개변수를 받는지, 어떤 값을 반환하는지 등을 명확하게 설명하여 코드의 가독성과 유지보수성을 높여준다.

JSDoc에 대한 더 자세한 내용은 JSDoc에서 확인할 수 있다.

3. 1. 추가 태그 정보

현대 JSDoc에서 자주 사용되는 몇 가지 주석 태그는 다음과 같다.

태그설명
`@author영어`개발자 이름
`@constructor영어`함수를 생성자(constructor)로 표시
`@deprecated영어`메서드를 사용 중단으로 표시
`@exception영어``@throws영어`의 동의어
`@exports영어`모듈에서 내보낸 멤버를 식별
`@param영어`메서드 매개변수를 문서화. 중괄호 안에 데이터 유형 표시기를 추가할 수 있음.
`@private영어`멤버가 비공개임을 나타냄.
`@returns영어`반환 값을 문서화.
`@return영어``@returns영어`의 동의어
`@see영어`다른 객체와의 연관 관계를 문서화.
`@todo영어`누락/미완료된 사항을 문서화.
`@this영어`함수 내에서 키워드 `this`가 참조하는 객체의 유형을 지정.
`@throws영어`메서드에서 발생한 예외를 문서화.
`@version영어`라이브러리의 버전 번호를 제공.


4. 예시

javascript

/** @class 원을 나타내는 클래스 */

class Circle {

/**


  • Circle의 인스턴스를 생성합니다.

  • @author: moi
  • @param {number} r 원의 원하는 반지름입니다.
  • /

constructor(r) {

/** @private */ this.radius = r;

/** @private */ this.circumference = 2 * Math.PI * r;

}

/**

  • 지름으로부터 새로운 Circle을 생성합니다.

  • @param {number} d 원의 원하는 지름입니다.
  • @return {Circle} 새로운 Circle 객체입니다.
  • /

static fromDiameter(d) {

return new Circle(d / 2);

}

/**

  • Circle의 둘레를 계산합니다.

  • @deprecated 1.1.0 이후; getCircumference를 사용하세요
  • @return {number} 원의 둘레입니다.
  • /

calculateCircumference() {

return 2 * Math.PI * this.radius;

}

/**

  • 미리 계산된 Circle의 둘레를 반환합니다.

  • @return {number} 원의 둘레입니다.
  • @since 1.1.0
  • /

getCircumference() {

return this.circumference;

}

/**

  • Circle의 문자열 표현을 찾습니다.

  • @override
  • @return {string} 이 Circle의 사람이 읽을 수 있는 표현입니다.
  • /

toString() {

return `[반지름이 ${this.radius}인 Circle 객체입니다.]`;

}

}

/**

  • 원을 출력합니다.

  • @param {Circle} circle
  • /

function printCircle(circle) {

/** @this {Circle} */

function bound() { console.log(this) }

bound.apply(circle);

}

```

`@class`와 `@constructor` 태그는 실제로 생략될 수 있다. ECMASyntax는 그들의 정체성을 명확하게 하는 데 충분하며, JSDoc은 그것을 활용한다.[5] `@override` 또한 자동으로 추론될 수 있다.[6]

```javascript

/**

  • Circle의 인스턴스를 생성합니다.

  • @constructor
  • @author: 나
  • @this {Circle}
  • @param {number} r 생성하려는 원의 반지름.
  • /

function Circle(r) {

/** @private */ this.radius = r;

/** @private */ this.circumference = 2 * Math.PI * r;

}

/**

  • 지름으로부터 새로운 Circle을 생성합니다.

  • @param {number} d 생성하려는 원의 지름.
  • @return {Circle} 새로운 Circle 객체.
  • /

Circle.fromDiameter = function (d) {

return new Circle(d / 2);

};

/**

  • Circle의 원주를 계산합니다.

  • @deprecated
  • @this {Circle}
  • @return {number} 원의 원주.
  • /

Circle.prototype.calculateCircumference = function () {

return 2 * Math.PI * this.radius;

};

/**

  • Circle의 계산된 원주를 반환합니다.

  • @this {Circle}
  • @return {number} 원의 원주.
  • /

Circle.prototype.getCircumference = function () {

return this.circumference;

};

/**

  • Circle의 문자열 표기를 반환합니다.

  • @override
  • @this {Circle}
  • @return {string} 이 Circle의 사람이 읽기 쉬운 표기.
  • /

Circle.prototype.toString = function () {

return "A Circle object with radius of " + this.radius + ".";

};

5. JSDoc 활용 사례

JSDoc은 다양한 개발 도구 및 환경에서 활용되고 있다.


  • 구글의 Closure Linter와 Closure Compiler는 JSDoc을 사용하여 자바스크립트 코드를 검사하고 최적화한다. 특히, Closure Compiler는 타입 정보를 추출하여 출력된 자바스크립트를 최적화하는 데 활용한다.[7]
  • TypeScript는 JSDoc 타입 주석을 사용하여 자바스크립트 파일에 대한 타입 검사를 수행할 수 있다.[7]
  • 널리 사용되는 편집기 Sublime Text는 DocBlockr 또는 DoxyDoxygen 플러그인을 통해 JSDoc을 지원한다.
  • IntelliJ IDEA, WebStorm, NetBeans, Visual Studio Code, RubyMine과 같은 JetBrains의 다양한 제품은 JSDoc 구문을 이해한다.
  • 이클립스 기반의 Aptana Studio는 ScriptDoc을 지원한다.
  • Mozilla Inline Editor인 Mozile은 JSDoc.pm을 사용한다.
  • Helma 애플리케이션 프레임워크는 JSDoc을 사용한다.
  • SproutCore 문서는 JSDoc을 사용하여 생성되었다.
  • Visual Studio, WebStorm 및 많은 다른 통합 개발 환경 또는 텍스트 편집기는 JSDoc 주석을 기반으로 코드 완성 및 기타 지원을 제공한다.
  • 오픈 소스 Atom 편집기는 atom-easy-jsdoc 플러그인을 통해 JSDoc을 지원한다.

6. 한국 내 JSDoc 활용

JSDoc은 여러 통합 개발 환경(IDE) 및 텍스트 편집기에서 지원된다.


  • Sublime Text는 DocBlockr 또는 DoxyDoxygen 플러그인을 통해 JSDoc을 지원한다.
  • IntelliJ IDEA, NetBeans, RubyMine|루비마인영어은 JSDoc 구문을 인식할 수 있다.
  • 이클립스 IDE에는 JSDoc 구문을 인식하도록 해주는 확장 기능이 있다. 이클립스 기반의 Aptana Studio|앱타나 스튜디오영어는 ScriptDoc을 지원한다.
  • Visual Studio나 WebStorm|웹스톰영어 등의 통합 개발 환경 (IDE) 및 텍스트 편집기는 JSDoc 주석에 기반한 코드 완성 기능 등의 코딩 지원 기능을 제공한다.
  • 오픈 소스 편집기 Atom은 atom-easy-jsdoc 플러그인을 통해 JSDoc을 지원한다.

참조

[1] 웹사이트 Rhino example: jsdoc.js https://github.com/m[...] Mozilla project 1999-05-06
[2] 웹사이트 JSDoc https://sourceforge.[...] 2013-04-15
[3] 웹사이트 jsdoc-toolkit https://code.google.[...]
[4] 웹사이트 JSDoc https://github.com/j[...] jsdoc 2019-09-04
[5] 웹사이트 ES 2015 Classes https://jsdoc.app/ho[...]
[6] 웹사이트 "@override" https://jsdoc.app/ta[...]
[7] 웹사이트 Type Checking JavaScript Files https://www.typescri[...]
[8] 웹사이트 jsdoc.js https://lxr.mozilla.[...] Mozilla project 1999-05-06


본 사이트는 AI가 위키백과와 뉴스 기사,정부 간행물,학술 논문등을 바탕으로 정보를 가공하여 제공하는 백과사전형 서비스입니다.
모든 문서는 AI에 의해 자동 생성되며, CC BY-SA 4.0 라이선스에 따라 이용할 수 있습니다.
하지만, 위키백과나 뉴스 기사 자체에 오류, 부정확한 정보, 또는 가짜 뉴스가 포함될 수 있으며, AI는 이러한 내용을 완벽하게 걸러내지 못할 수 있습니다.
따라서 제공되는 정보에 일부 오류나 편향이 있을 수 있으므로, 중요한 정보는 반드시 다른 출처를 통해 교차 검증하시기 바랍니다.

문의하기 : help@durumis.com