반응형
JsDoc이란?
JavaScript용 API 문서 생성기
=> 즉 완전 유용한 주석이다
=> VSCode, Webstorm 등 여러 IDE에서 지원함
일반적으로 사용하는 주석
/**/
//
JsDoc 주석
/**
*
*
*/
=> /** 으로 입력하면 사용 가능
일반 주석과의 공통점, 차이점
| 일반 주석 | JSDoc | |
| 기능 | 함수의 기능 매개변수, 리턴값 |
함수의 기능 매개변수, 리턴값 |
| 주석 단 대상 hover 시 | 별 반응 없음 | 함수와 변수 등 주석을 단 내용이 보여짐 |
=> 매개변수와 리턴값 이외에도 다양한 값 설정이 가능함
실제 사용되는 모습
/**
* 이름과 나이 입력시 해당 내용으로 인사하는 함수
*/
function Hi(name, age) {
console.log(`hi $age years old $name!`);
}
Hi('Octopus', 23);
주로 사용되는 요소
@param {} 변수명
- 매개변수에 대해 설명 시 사용
- 중괄호 안에는 데이터 타입을 작성(데이터 타입 작성은 optional)
- 변수명 뒤에는 해당 매개변수에 대한 설명 작성
- 매개변수에 대한 설명은 스페이스바 또는 - 뒤에 작성 가능
/**
* 이름과 나이 입력시 해당 내용으로 인사하는 함수
* @param {string} name 누군가의 이름
* @param {number} age - 누군가의 나이
*/
function Hi(name, age) {
console.log(`hi ${age} years old ${name}!`);
}
Hi('Octopus', 23);
@return [<some text>]
- 리턴값으로 반환되는 값 설명 시 사용
/**
* 이름과 나이 입력시 해당 내용으로 인사하는 함수
* @param {string} name 누군가의 이름
* @param {number} age - 누군가의 나이
* @return 이름과 나이가 들어간 인사 문구
*/
function Hi(name, age) {
console.log(`hi ${age} years old ${name}!`);
}
Hi('Octopus', 23);
@deprecated [<some text>]
- 사용 중지된 함수를 나타낼 때 사용
- 대괄호 안에는 버전 등의 정보에 대한 추가 텍스트 작성 가능(실제로는 스페이스바로 간격을 두고 괄호는 사용하지 않음)
- 함수에 취소선이 그어지는 것을 확인할 수 있음
/**
* @deprecated
*/
function Hi(name, age) {
console.log(`hi ${age} years old ${name}!`);
}
Hi('Octopus', 23);
@type [<some text>]
- 변수를 만들 때 타입 지정 시 사용
- 타입스크립트와 비슷한 효과를 냄
- 타입별로 적절한 메서드를 띄워줌
/**@type {string | number} */
var name = 'Chaz';
/**@type {number[]} */
var num = [1,2,3];
@readonly
- read-only라는 사실을 명시하고자 사용
- 실제로 read-only 처리가 되지는 않음(권고용)
/**
* @readonly
*/
@todo [<some text>]
- 해야 할 내용 작성 시 사용
/**
* @todo Write the documentation.
* @todo Implement this function.
*/
@version [<some text>]
- 버전에 대한 정보를 명시하고자 사용
/**
* @version 1.2.3
*/
@see [<some text>]
- 참고할 부가 정보를 작성할 때 사용
- 링크 따위가 해당됨
/**
* @see https://ooctopushead.tistory.com/
*/
자세한 내용은 하단 링크 참고하시길!
TypeScript 대신 @type을 사용하는 이유?
- 개발 초기 변경 사항이 많은 경우 타입스크립트가 엄격해 적합하지 않음
TS -> JS 변환 과정이 번거로움- TS -> JS 변환 시 코드양이 많아지고, 가독성이 떨어지게 됨
반응형