[ TypeScript ] 협업을 위한 interface 에 힌트 주석 달기.

 

 

 

 

ts로 프로젝트를 개발 중에 interface에 추가적인 설명이 있으면 좋겠다~! 라는 생각이 들어서 평소에는 method나 method parameter에 대한 설명을 달아줄 때 자주 사용하던 JSDoc을 이용하여 interface 설명을 추가해 보았다.

 

 

먼저 JSDoc에 대해 설명하자면, JSDoc은 자바스크립트용 API 문서 생성기로 자바스크립트 애플리케이션 또는 라이브러리의 API를 문서화하는 목적으로 사용한다. module, namespaces, classes, methods, method parameters 등과 같은 항목들을 문서화할 수 있다.

JSDoc은 코드 자체와 함께 소스코드에 직접 문서 주석을 추가하는 기능을 가지고있다.

 

 

JSDoc 주석은 일반적으로 문서화하려는 코드 바로 앞에 위치해야 하며 각 주석은 JSDoc 파서에서 인식되도록 /** 시퀀스로 시작해야 한다. /*, /***, 또는 3개 이상의 별표로 시작하는 주석과 일반적인 자바스크립트 주석은 무시된다. 이 기능은 주석 블록의 파싱을 억제할 수 있도록 하기 위함이다.

 

 

 

 

1. 가장 단순한 버전의 문서화 방법.

/** This is a description of the foo function. */
function foo() {
}

 

 

 

 

 

2. JSDoc 태그를 사용하여 코드를 설명하는 방법.

/**
 * Represents a book.
 * @constructor
 */
function Book(title, author) {
}

 

 

 

 

 

3. 태그를 사용하여 추가 정보를 추가하는 방법. 

/**
 * Represents a book.
 * @constructor
 * @param {string} title - The title of the book.
 * @param {string} author - The author of the book.
 */
function Book(title, author) {
}

 

 

 

 

---

 

 

 

interface ICardSection {
    backgroundcolor?: string;
    bordercolor?: string;
    borderradius?: number;
    width?: string;
    height?: string;
    children: React.ReactNode;
    /**
     * margin은 단위까지 적어야 한다.
     */
    margin?: string;
}

그래서 위와 같이 interface에 JSDoc을 추가하여 정보를 문서화하면, 아래와 같이 props에 마우스를 올리면 추가 정보가 노출된다.

 

 

 

 

 

 

 

 

 

 

 

 

 

---

 

🌸 출처 🌸

 

JSDoc

poiemaweb - JSDoc을 사용하는 방법