JSDoc을 설정 파일로 빼서 사용해보도록 합시다

📌 연관 글

1. Javascript Documentation 라이브러리 JSDoc를 사용해 봅시다
2. JSDoc을 설정 파일로 빼서 사용해보도록 합시다
3. JSDoc에서 템플릿을 사용해 보도록 합시다
4. Webpack과 JSDoc을 연동하여 자동화를 시켜봅시다

---

자 우리는 JSDoc 설치를 완료하였고 직접 Documentation을 만들기까지 하였습니다.

어떤가요 참 쉽지 않나요?

하지만 각각 필요한 옵션들을 커맨드라인에 입력 후 Documentation을 만드는 일은 참 번거로운 일입니다.

그렇기 때문에 이 JSDoc은 설정파일로 만들어서 사용할 수 있도록 기능을 추가해 놨습니다.

그럼 한번 알아보도록 하겠습니다.

JSDoc

---

JSDoc 설정 파일 만들기

자 저희는 이전 포스트에서 아래 사진과 같은 구조를 만들었습니다.

(만약 이전 포스트를 보고오지 않으셨다면 링크를 클릭하여 이전 포스트를 보고오세요)

이전 포스트에서 만든 구조

이제 저희는 jsdoc.config.json이라는 파일 하나를 만들겠습니다.

그 후의 구조는 아래와 같습니다.

jsdoc.config.json 파일 생성

그런 다음 jsdoc.config.json에는 아래와 같이 입력합니다.

{
  "plugins": [],
  "recurseDepth": 10, // -r 명령 행 플래그로 재귀가 사용 가능한 경우 JSDoc은 10 레벨 깊이의 파일을 검색합니다.
  "source": {
    "includePattern": ".+\\.js(x|doc)?$", // js, jsx, jsdoc 이라는 확장자를 가진 것을 Docs로 변환합니다.
    "excludePattern": "(^|\\/|\\\\)_" // 밑줄로 시작하거나 밑줄로 시작하는 디렉토리에있는 모든 파일은 무시됩니다.
  },
  "sourceType": "module", // ES 2015를 지원하기 위해 적용
  "tags": {
    "allowUnknownTags": true // JSDoc이 알 수 없는 태그를 지원하도록 설정
  },
  "opts": {
    "encoding": "utf8", // Docs에서 한글을 사용할 수 있도록 설정
    "destination": "./docs" // 기존에 생성되던 out이라는 폴더를 docs라는 폴더로 생성
  }
}

이게 가장 기본적인 설정입니다.

물론 여기서 더 추가할 수 도 있지만, 그건 일단 설정파일을 빌드해보고 더 추가해보도록 하겠습니다.

커맨드라인에 아래 커맨드를 입력해 보도록하죠

$ ./node_modules/.bin/jsdoc -c .\jsdoc.config.json .

그럼 docs라는 폴더가 하나 생성된 것을 알 수 있습니다.

그리고 index.html을 열어보면 정상적으로 Documentation이 생성된 것을 알 수 있습니다.

하지만 기존과 달라진 점을 찾으라면 딱히 달라진 점은 없습니다.

그럼 더 추가해 보도록 할까요?

 

JSDoc에서 마크다운 추가하기

JSDoc-Home 화면

자 위 사진을 보면 index.html에 Home 화면이 그냥 비어있습니다.

너무 공허해 보여셔 Documentatino인지도 모를정도로 비어있네요....

우리는 이 Home화면을 README.md파일을 이용하여 꾸며볼 것입니다.

일단 그럼 README.md파일을 만들어야 하겠죠?

README.md파일을 만듭니다.

 

README.md 파일 생성

그 후 README.md에 원하시는 텍스트를 입력한 후 저장을 합니다.

저는 일단 "홈 화면 입니다." 라는 텍스트를 입력 후 저장하도록 하겠습니다.

README.md

JSDoc은 README.md파일을 자동적으로 Home화면으로 지정합니다.

하지만 README.md는 Markdown언어기 때문에,

JSDoc이 Markdown언어를 인식할 수 있도록  플러그인을 추가해야합니다.

그럼 Markdown언어를 사용할 수 있도록 추가 설정을 해보도록 하겠습니다.

아래와 같이 적용해 주세요

{
  "plugins": ["node_modules/jsdoc/plugins/markdown"], // Markdown을 사용하기 위해 플러그인을 추가합니다.
  "recurseDepth": 10, // -r 명령 행 플래그로 재귀가 사용 가능한 경우 JSDoc은 10 레벨 깊이의 파일을 검색합니다.
  "source": {
    "include": ["./"],	// ./에 includepattern에 해당하는 파일을 대상으로 함
    "includePattern": ".+\\.js(x|doc)?$", // js, jsx, jsdoc 이라는 확장자를 가진 것을 Docs로 변환합니다.
    "excludePattern": "(^|\\/|\\\\)_" // 밑줄로 시작하거나 밑줄로 시작하는 디렉토리에있는 모든 파일은 무시됩니다.
  },
  "sourceType": "module", // ES 2015를 지원하기 위해 적용
  "tags": {
    "allowUnknownTags": true // JSDoc이 알 수 없는 태그를 지원하도록 설정
  },
  "opts": {
    "encoding": "utf8", // Docs에서 한글을 사용할 수 있도록 설정
    "destination": "./docs" // 기존에 생성되던 out이라는 폴더를 docs라는 폴더로 생성
    "readme": "README.md",  // README.md를 추가
  }
}

추가된것은 plugin항목과 include 항목과 opts에 readme를 추가한 것 입니다.

자세한 것은 주석으로 달아놓았기 때문에 따로 설명을 하지 않았습니다.

그리고 다시 JSDoc을 이용해 Documentation 빌드를 해보도록 할까요?

아래 커맨드를 커맨드라인에 입력해 주신후,

./docs 폴더에 index.html을 실행시켜보도록 합시다.

$ ./node_modules/.bin/jsdoc -c .\jsdoc.config.json .

README.md를 홈화면에 적용시킨 모습

어때요 참 쉽지 않나요?

 

JSDoc에 설정파일에서 특정파일만 문서화 시키는 방법

자 저희는 프로젝트를 생성하여 처음부터 JSDoc을 사용해서 문서화를 하였습니다.

하지만 기존의 진행하던 프로젝트같은 경우 JSDoc을 추가하여 문서화를 진행할 때,

JSDoc이 이해할 수 없는 주석들이 존재하여 Documentation을 만드는데 오류가 발생하거나 적용이 안되는 경우가 존재합니다.

이러한 경우엔 어떻게 할까요?

그렇습니다.

제목과 같이 파일 단위로 하나하나 JSDoc이 이해할수 있는 주석들로 변환해 준 후,

컴파일을 해주면 됩니다.

 

 

방법은 간단합니다.

위 사진의 빨간색 네모와 파란색 네모 같이 그냥 파일의 경로를 지정해 주고 includePatten속성에서 js를 지워버리면,

JSDoc이 알아서 그 파일만 컴파일시켜 줍니다.

그 후 컴파일 시키면

기존과 동일한 문서가 생성되게 됩니다.

어때요 간단하죠?

 

마치며

이것으로 저희는 JSDoc 설정파일을 만들어서 원하는 대로 설정을 관리할 수 있도록 만들었습니다.

이 jsdoc.config.json이란 파일은 다른 프로젝트에서도 계속 사용할 수 있으므로,

꼭 만들어서 사용하시는 것을 추천드립니다.

또한 다음 포스팅인 Template 변경과 Webapck 연동에서도, 이 jsdoc.config.json 파일을 사용할 예정입니다.

꼭 프로젝트를 유지해 주시길 바랍니다.

그럼 다음에 뵙겠습니다.😘