[JavaScript] JSDoc

JS Doc 이란?

• JavaScript 소스 코드에 대한 설명을 하기 위해 사용되는 마크업 언어
• 태그를 이용하여 문서의 구조를 명기
• 주 목적은 JavaScript 앱 또는 라이브러리 API를 문서화
  - 모듈, 네임스페이스, 클래스, 메서드, 파라미터 등과 같은 항목을 문서화할 것으로 가정
• /** */ 로 Scope 지정
• @ 을 사용하여 태그를 표현
• block tag 와 inline tag 로 나눠진다
  - 사용 문법이 다름
• 일반적으로 코드가 문서화되기 직전에 배치되어야 한다

Block tag

/**
* Bar function.
* @alias bar
*/
function foo() {}

inline tag

/**
* See {@link MyClass} and [MyClass's foo property]{@link MyClass#foo}.
* Also, check out {@link http://www.google.com|Google} and
* {@link https://github.com GitHub}.
*/
function myFunction() {}

기본 사용방법

/** This is a description of the foo function. */
function foo() {
}

태그를 사용하면?

/**
* Represents a book.
* @constructor
*/
function Book(title, author) {
}

• Book 함수가 생성자 함수라는 것을 @constructor 태그를 사용하여 설명하고 있다

/**
* Represnets a book.
* @constructor
* @param {string} title - the title of the book
* @param {string} author - The author of the book
*/
function Book(title, author) {
}

• 생성자 함수 Book에 전달되는 parameter 까지 추가
• @param 태그에 중괄호로 string 이라는 타입을 지정하고 뒤에는 parameter의 이름과 설명을 정의

JSDoc Comment Tags

• Document by Microsoft

@deprecated	@deprecated description	Specifies a deprecated function or method
@description	@description description	Specifies the description for a function or method
@param	@param {type} parameterNamedescription	Specifies information for a parameter in a function or method TypeScript also supports @paramTag
@property	@property {type} propertyName	Specifies information, including a description, for either a field or member that's defined on an object
@returns	@returns {type}	Specifies a return value For TypeScript, use @return Type instead of @returns
@summary	@summary description	Specifies the description for a function or method (same as @description)
@type	@type {type}	Specifies the type for a constant or a variable
typedef	@typedef {type} customTypeName	Specifies a custom type

/**
* 기본 작성 기준
* boolean 값이라면 언제 true이고 언제 false인지 작성
* 숫자라면 범위나 값의 의미를 작성
* enum이면 어떤 값을 쓸 수 있는지 나열
* 이 메서드를 호출하기 전후에 해야하는 작업이 있다면 해당 내용을 작성
* 특정 상황에서 이 메서드를 사용하지 않아야 한다면 해당 내용을 작성

* @global 전역에 해당하는 내용을 작성

* @function 어떤 parameter를 받아서 어떤 값을 return 하는 함수인지 작성

* @param 어떤 타입의 parameter를 전달해야 하는지 작성
* 허락되지 않은 parameter를 전달했을 때 어떤 일이 발생하는지 작성

* @return 무엇을 반환해야 하는지 작성
* 문제가 발생했을 때 일반 상황과 다른 의미의 값을 반환한다면 해당 내용을 작성

* @callback 전역인지 지역인지 구분 및 어떤 함수인지 작성

* @event 어떤 이벤트인지 작성
*/

---

https://jsdoc.app/