typescript interface를 jsdoc으로 주석달 때

Question

안녕하세요 ㅎㅎ

예를 들어 다음과 같은 인터페이스가 있고 해당 인터페이스 상단에 jsdoc기반으로 주석달 때 다음과 같이 주석을 다는게 맞을까요?

/**
 * 테스트 결과 인터페이스
 *
 * 이 인터페이스는 API 테스트 결과를 캡처하기 위한 정보를 담습니다.
 *
 * @property {HttpMethod} method - HTTP 메소드 (예: GET, POST 등).
 * @property {string} url - 요청 URL.
 * @property {ApiDocOptions} options - API 문서 생성 옵션.
 * @property {object} request - 요청 관련 정보.
 * @property {unknown} [request.body] - 요청 바디 (선택 사항).
 * @property {Record<string, string | unknown>} [request.headers] - 요청 헤더 (선택 사항).
 * @property {Record<string, string | unknown>} [request.queryParams] - URL 쿼리 파라미터 (선택 사항).
 * @property {Record<string, string | unknown>} [request.pathParams] - URL 경로 파라미터 (선택 사항). 
 */
export interface TestResult {
    method: HttpMethod
    url: string
    options: ApiDocOptions
    request: {
        body?: unknown
        headers?: Record<string, string | unknown>
        queryParams?: Record<string, string | unknown>
        pathParams?: Record<string, string | unknown>
    } 
}

감사합니다.

zerocho · Answer

ts이면 typedoc도 고려해볼만 하고요. 이미 타입이 달려있으므로 {HttpMethod}나 선택 사항같은 건 안 적으셔도 되긴 합니다.

communityai8509 · Answer

안녕하세요, 인프런 AI 인턴입니다. 큰돌님.

타입스크립트의 인터페이스에 대해 JSDoc 주석을 다는 방법에 대해 문의해 주셨습니다. 전달해 주신 예시는 매우 잘 작성되었으며, JSDoc으로도 잘 호환됩니다. 각 속성에 대한 설명과 타입을 명시하여 코드의 가독성과 유지보수성을 높이는 데 도움이 됩니다.

해당 방법으로 인터페이스에 주석을 다는 것은 적절합니다. 또한, 주석을 통해 인터페이스의 각 속성이 어떤 역할을 수행하는지, 그리고 각 속성의 타입이 무엇인지 명확히 음으로써 다른 개발자가 코드를 쉽게 이해할 수 있도록 돕고 있습니다.

더불어 아래 링크를 참고해보시면, 타입스크립트 프로젝트에서 JSDoc을 활용하여 더 많은 관리 방식이나 팁을 얻을 수 있습니다:
- 타입스크립트와 JSDoc

저는 질문자님의 이해를 돕고자 지식공유자님의 기존 답변을 참고하여 유사한 답변 링크를 추천해드리고 있습니다. 현재 베타 기능으로 답변이 만족스럽지 않을 수 있는 점 양해 부탁드립니다. 🙏 추가적으로 궁금한 점이 있으시면, 이어서 질문해 주세요. 곧 지식공유자께서 답변해 주실 것입니다.

Inflearn Community Q&A

typescript interface를 jsdoc으로 주석달 때