2022-07-26
타입스크립트를 공부하다가 보니 자바스크립트내에서 되게 신기하게 타입스크립트처럼 약간의 능력을 해줄 수 있는 JSdoc이라는 것을 알게되어 간단하게 정리를 해놓을려고 한다
🚩JsDoc이란
jsdoc은 이름그대로에서도 느껴지듯이 자바스크립트용 api 문서 생성기이다.문서 주석을 달면서 해당 작성한 문서들을 보기좋게 readme.md하는 것처럼 주석에 대한 내용들을 가지고 html파일들을 만들어준다.
🔑대표적 기능
사실 나는 이걸 타입스크립트처럼 어느정도 타입추론의 기능을 자바스크립트에 넣어 버그 픽스를 알려주는 용도로 사용했기에
1.타입추론
실시간으로 런타임 상황에서 내가 설정한 파라미터의 타입에 위배되는 자료형을 넣거나 할때 마치 타입스크립트를 사용하듯 에러를 알려주는 것을 알 수 있다.
참 신기한일이지 않은가??
자바스크립트 파일인데 타입에 대한 오류를 알려주는게???
2.버그픽스 리포트
버젼별로 개선점등을 작성하면 자동으로 뚝딱 아래와 같이 버젼별로 변화사항을 한눈에 볼 수 있다.
3.말 그대로 api문서를 생성해준다
개발자가 서버에 어떤 데이터를 요청하고 어떤식으로 응답받는지에 대한 api명세서를 주석으로 기술하면 자동으로 만들어준다
🙋♂️사용방법
기본적으로 jsdoc은 /**
으로 시작하여
끝나는 방식으로 주석을 써야 인식을 한다.
<예시>
여기서 상황은 fetchuser()라는 api를 하나 만들었는데 해당 api는 반환형이 axos.get(url)로 부터 나오는 것으로 보아
우리는 Promise 비동기처리 객체임을 유추할 수 있다.
따라서 우리는 작성한 메소드 위에다가
주석으로
@returns {Promise<User>}
//이 뜻은 어떤 형태를 반환한다는 것을 명시해두는 것그럼 여기서 User가 타입스크립트 기준 상으로 제네릭으로 들어가는 것을 볼 수 있다.
따라서 User라는 것에 대해 정의를 또 해줄 수 있다.
여기서 보면
@typedef {자료형} 자료명
@property {자료형} 변수명
//typedef를 통해 객체에 대한 정보를 미리 명시해둘 수 있다
//이렇게 해두면 서버에서 응답받아올 정보들을 이와같이
//저장해둘 수 있어 굳이 매번 체크할 필요없다
//property는 그 안에 있는 프로퍼티들을 지정해준다고 생각하면 된다@typedef은 타입스크립트에서 별칭 달아줄 때 사용된
type 별칭 =Object
//같은 의미이다이 말고도 다양한 태그들이 존재한다.
/**
* 기본 작성 기준
* boolean 값이라면 언제 true이고 언제 false인지 작성
* 숫자라면 범위나 값의 의미를 작성
* enum이면 어떤 값을 쓸 수 있는지 나열
* 이 메서드를 호출하기 전후에 해야하는 작업이 있다면 해당 내용을 작성
* 특정 상황에서 이 메서드를 사용하지 않아야 한다면 해당 내용을 작성
* @global 전역에 해당하는 내용을 작성
* @function 어떤 파라미터를 받아서 어떤 값을 반환하는 함수인지 작성
* @param 어떤 타입의 파라미터를 전달해야 하는지 작성
* 허락되지 않은 파라미터를 전달했을 때 어떤 일이 발생하는지 작성
* @return 무엇을 반환해야 하는지 작성
* 문제가 발생했을 때 일반 상황과 다른 의미의 값을 반환한다면 해당 내용을 작성
* @callback 전역인지 지역인지 구분 및 어떤 함수인지 작성
* @event 어떤 이벤트인지 작성
*/출처: https://jsdoc.app/
이러한 각각의 jsdoc 태그들은 api문서를 만들어줄 때에도 인식이 된다.
@ts-check 사용해보기
지금까지 위해서 사용한것처럼 태그들을 사용해보면 명시를 통해 이와 같은 자동완성에 대한 기능을 받을 수 있다
하지만 저기까지만 하면 자료형에 대한 에러는 안 알려주게 되는데 해당 기능까지 원하면
코드 상단에 위와 같이
@ts-check를 해주어야 실질적으로 밑에서처럼 타입에 대한 에러처리를 타입스크립트처럼 해주게 된다
👨💻환경설정
npm init -y
//기본 package.json 만들어주고
npm i --save-dev jsdoc
//jsdoc 패키지에 추가이렇게 하고 내가 만들고자하는 파일에 템플릿들을 사용하여
한 번 표기를 하나 해두자 파일명은 예를 들어 index.js
/**function say_sum
* @param {number} a 주석내용-설명글들
* @param {number} b 주석내용-설명글들
* @returns {number} a+b
*/
const say_sum=(a,b)=>return a+b;따라서 해당 문서를 문서화 해보는 방법두가지가 있다
방법1.명령어를 쳐서
./node_modules/.bin/jsdoc index.js
//나처럼 로컬로 설치했을경우 jsdoc경로를 나타내야함그럼 out이라는 폴더가 생성되고 그안에 index.html이라는 것이 생성되어 확인해보면 해당 index.js에 있던 주석들을 가지고 api명세서를 만들어준 것을 확인할 수 있다.
최종적으로 이와 같은 html문서를 확인해볼 수 있다
방법2. jsdoc.config.json를 통해서
jsdoc 홈페이지를 가보면 기본적으로 제공하는
configuration 코드들이 있다 여기서 복사를해서
jsdoc.config 붙여넣어주자
추가적으로 여기까지만 하면 특정 src폴더나 아래에 대해서는 문서화를 안해주기에 include로 원하는 폴더를 더 추가해주자
"source": {
"include": [".", "src"],
//요부분
"includePattern": ".+\\.js(doc|x)?$",
"excludePattern": "(^|\\/|\\\\)_"
},그리고 최종적으로
./node-modules/.bin/jsdoc -c jsdoc.config.json
//을 해주면 자동으로 전체에 대해서 api문서화를 시켜준다해주면 모든 완성!
🚩Readme.md를 만들려면
jsdoc.config.json에
"plugins": [
"plugins/markdown"
],
"opts": {
"readme": "README.md"
}추가해주기 단 이전에 readme.md를 하나 미리 만들고 거기다가 좀 원하는 마크다운을 작성해주고 나면
readme 내용과 각 모듈별 api를 같이 합쳐서 보여준다.
🔑명령어 줄이기
지금 로컬에 jsdoc을 설치하므로써 상당히 명령어가 길다.
따라서 이걸 좀 편리하게 하기 위해서는
웹팩을 설치하고
(앞선 웹팩 포스팅 참고해보기)
webpack.config.js에
const path = require("path");
const JsDocPlugin = require("jsdoc-webpack-plugin");
module.exports = {
entry: "./index.js",
output: {
path: path.join(__dirname, "dist"),
filename: "main.js"
},
plugins: [
new JsDocPlugin({
conf: "jsdoc.config.json",
cwd: ".",
preserveTmpFile: false
})
]
};추가해주고 package.json에서
start명령어에 webpack을 추가해주기!
