[JavaScript] JSDoc

Hyunji·2022년 5월 11일
0

공부

목록 보기
25/35
post-thumbnail

JS Doc 이란?

  • JavaScript 소스 코드에 대한 설명을 하기 위해 사용되는 마크업 언어
  • 태그를 이용하여 문서의 구조를 명기
  • 주 목적은 JavaScript 앱 또는 라이브러리 API를 문서화
    - 모듈, 네임스페이스, 클래스, 메서드, 파라미터 등과 같은 항목을 문서화할 것으로 가정
  • /** */ 로 Scope 지정
  • @ 을 사용하여 태그를 표현
  • block taginline 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 descriptionSpecifies a deprecated function or method
@description@description descriptionSpecifies the description for a function or method
@param@param {type} parameterNamedescriptionSpecifies information for a parameter in a function or method
TypeScript also supports @paramTag
@property@property {type} propertyNameSpecifies 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 descriptionSpecifies 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} customTypeNameSpecifies a custom type
/**
* 기본 작성 기준
* boolean 값이라면 언제 true이고 언제 false인지 작성
* 숫자라면 범위나 값의 의미를 작성
* enum이면 어떤 값을 쓸 수 있는지 나열
* 이 메서드를 호출하기 전후에 해야하는 작업이 있다면 해당 내용을 작성
* 특정 상황에서 이 메서드를 사용하지 않아야 한다면 해당 내용을 작성

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

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

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

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

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

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

https://jsdoc.app/

profile
성장중인 개발자

0개의 댓글