Typescript source file을 문서화하기
백엔드
Typescript source file을 문서화하기
두줄요약
TypeScript AST를 분석해 인터페이스·enum·type을 Markdown으로 문서화하는 라이브러리를 소개했습니다. 수동 문서 동기화 부담을 줄이고 템플릿 기반 출력 구조를 구성했습니다.
문제 상황
- Mongoose 스키마, TypeScript Interface, Confluence 문서의 수동 동기화로 인한 누락·오기입과 관리 포인트 증가
- 정보 불일치 발생 시 대조와 추적에 드는 운영 부담
구조와 흐름
- TypeScript Compiler API의
createSourceFile기반 소스 파일 AST 생성 - InterfaceDeclaration, EnumDeclaration, TypeAliasDeclaration과 속성 시그니처·JSDoc 파싱
- 파싱 결과를 Handlebars.js 템플릿으로 조합해 Markdown 문서 출력
선택 이유
- 외부 파서 없이 TypeScript 패키지만으로 소스 분석과 AST 순회 가능
- 공용 패키지 분리와 다양한 적용 사례 대응을 위한 Handlebars.js 템플릿 도입
주의할 점
- TypeScript 모듈 활용 관련 공식 문서 부족과 AST 구조 탐색 난이도
- Handlebars.js 템플릿 오류 위치 파악의 디버깅 부담
- 대형 프로젝트의 단일 출력 파일 비대화와 class 문법 미지원