[jsdoc] 사용해보기

KoEunseo·2023년 2월 1일

typescript

목록 보기

10/23

원티드 프리온보딩 신청을 또 했다.
내일까지 과제를 해야하는데... 포폴을 만드느라고 이제야 시작해보려고 한다 흑흑

JSCoc

jsdoc 홈페이지. 세기말 감성이 돋보인다. 처음엔 이게 맞나 당황스러웠으나 지금 살펴보니 jsdoc을 사용해 html파일이 생성되면 위와 같이 나오는듯 하다.
jsdoc 깃허브 레포지토리
타입스크립트 jsdoc 레퍼런스
자바스크립트용 api문서생성기.
1. 코드에 주석을 달고,
2. JSDoc3 도구로 해당 문서를 변환하면
이때, jsdoc ./파일경로/파일.js 해야한다.
3. html문서가 짠!

JSDoc 설치

npm install -g jsdoc

/** 이렇게 주석을 단다.*/

/** 설명을 쓰고
 * @태그도 할 수 있다.
 *
 */

커멘드라인에서 문서생성기 실행하기

아래 명령어를 치면 /out 이라는 폴더에 html파일이 생성된다.
--destination 이라는 옵션을 사용해서 다른폴더에 생성할수도 있는 모양.
jsdoc 문서이름.js

내가 사용한 jsdoc 문법들

author, see

작성자와 링크 등록

/**
 * @author Eunseo Go
 * @see <a href="https://ko-eunseo.github.io/wanted-pre-onboarding-challenge-fe-ts/index.html">배포링크</a>
 */

typedef, property

typedef가 있고 type이 있다. typedef는 복잡한 형태일때 사용.
property는 타입의 속성을 표기해준다.
기본적으로 @메서드 + {타입} + 속성이름 + '설명'
기본적으로 jsdoc 홈페이지와 타입스크립트 문서에 있는 jsdoc reference를 참고해 작성했다.

/**
 * Type of tag.
 * @typedef {Object} TagItem
 * @property {number} tagId - The id of the tag.
 * @property {string} tagName = the name of the tag.
 */

optional []

옵셔널한 속성은 대괄호로 감싸준다. 배포하고 보니 nullable이라고 표기된 것을 볼 수 있었다.

/**
 * Type of todo.
 * @typedef {Object} TodoItem
 * @property {number} id - The id of the todo.
 * @property {string} content - The content of the todo.
 * @property {boolean} isDone - Whether user did or not todo.
 * @property {string} category - The category of the todo.
 * @property {TagList} [tagList] - The tags of the todo.
 */

function, param, return, see, link

function: 함수
param: 매개변수
return: 반환값
see: 참고, link: 링크

/**
 * @function Create todo.
 * @param {string} content 
 * @param {string} category 
 * @param {string[]?} tags 
 * @return {TodoItem}
 * @see {@link TodoItem}
 */
const CreateTodo = (content, category, tag) => { };