|
| 1 | +# JsDoc |
| 2 | + |
| 3 | +## Summary |
| 4 | +JsDoc은 JavaScript 코드에 주석을 추가하여 함수, 변수, 클래스 등의 정보를 명확하게 문서화하는 도구이다. 주석 기반으로 작성되며, 코드 가독성을 높이고 IDE에서 자동완성 및 타입 힌트를 제공하는 데 도움을 준다. |
| 5 | + |
| 6 | +## Details |
| 7 | + |
| 8 | +### JsDoc 태그 리스트 |
| 9 | +JsDoc에서 자주 사용되는 태그와 그 기능은 다음과 같다. |
| 10 | + |
| 11 | +| 태그 | 설명 | |
| 12 | +|-------------|------| |
| 13 | +| `@param` | 함수의 매개변수 설명 | |
| 14 | +| `@returns` | 함수의 반환값 설명 | |
| 15 | +| `@type` | 변수의 타입 지정 | |
| 16 | +| `@typedef` | 사용자 정의 타입 선언 | |
| 17 | +| `@property` | 객체 속성의 타입 지정 | |
| 18 | +| `@example` | 코드 예제 제공 | |
| 19 | +| `@deprecated` | 더 이상 사용되지 않는 API 표시 | |
| 20 | +| `@see` | 참조할 관련 정보 추가 | |
| 21 | +| `@throws` | 함수에서 발생할 수 있는 예외 설명 | |
| 22 | +| `@async` | 비동기 함수 표시 | |
| 23 | +| `@callback` | 콜백 함수 타입 정의 | |
| 24 | +| `@private` | 내부적으로만 사용되는 항목 지정 | |
| 25 | +| `@public` | 공개 API로 사용됨을 명시 | |
| 26 | +| `@readonly` | 읽기 전용 속성 정의 | |
| 27 | + |
| 28 | +### JsDoc 사용 예시 |
| 29 | + |
| 30 | +```javascript |
| 31 | +/** |
| 32 | + * 두 개의 숫자를 더하는 함수입니다. |
| 33 | + * |
| 34 | + * @param {number} a - 첫 번째 숫자 |
| 35 | + * @param {number} b - 두 번째 숫자 |
| 36 | + * @returns {number} 두 숫자의 합 |
| 37 | + */ |
| 38 | +function add(a, b) { |
| 39 | + return a + b; |
| 40 | +} |
| 41 | + |
| 42 | +/** |
| 43 | + * 사용자 목록을 반환하는 함수입니다. |
| 44 | + * |
| 45 | + * @returns {User[]} 사용자 객체 배열 |
| 46 | + */ |
| 47 | +function getUsers() { |
| 48 | + return [ |
| 49 | + { id: 1, name: 'Alice', isActive: true }, |
| 50 | + { id: 2, name: 'Bob', isActive: false }, |
| 51 | + ]; |
| 52 | +} |
| 53 | +``` |
| 54 | + |
| 55 | +위 예시에서: |
| 56 | + |
| 57 | +- `add` 함수는 `@param` 태그를 사용하여 매개변수 `a`와 `b`의 타입과 설명을 제공하고, `@returns` 태그로 반환값의 타입과 설명을 명시한다. |
| 58 | +- `getUsers` 함수는 `@returns` 태그를 통해 `User` 객체의 배열을 반환함을 나타낸다. |
| 59 | + |
| 60 | +이러한 주석을 통해 코드의 가독성과 유지보수성이 향상되며, IDE의 자동완성 및 타입 힌트 기능을 활용할 수 있다. |
| 61 | + |
| 62 | +### JsDoc의 장점 |
| 63 | +JsDoc을 사용함으로써 다음과 같은 이점을 얻을 수 있다. |
| 64 | + |
| 65 | +1. **가독성 향상** |
| 66 | + - 함수와 변수의 용도를 명확하게 설명할 수 있어 코드 이해도를 높인다. |
| 67 | + |
| 68 | +2. **IDE 지원** |
| 69 | + - VSCode, WebStorm과 같은 IDE에서 자동완성 및 타입 힌트 기능을 제공받을 수 있다. |
| 70 | + |
| 71 | +3. **자동 문서화 가능** |
| 72 | + - `jsdoc` CLI 도구를 사용하면 HTML 형식의 API 문서를 자동으로 생성할 수 있다. |
| 73 | + |
| 74 | +4. **타입 검증 효과** |
| 75 | + - TypeScript 없이도 타입 힌트를 제공하여 코드의 안정성을 높일 수 있다. |
| 76 | + |
| 77 | +5. **협업 효율성 증가** |
| 78 | + - 여러 개발자가 동일한 프로젝트에서 협업할 때 함수와 객체의 역할을 쉽게 공유할 수 있다. |
| 79 | + |
| 80 | +### JsDoc의 단점 |
| 81 | +하지만 JsDoc에도 몇 가지 한계가 있다. |
| 82 | + |
| 83 | +1. **TypeScript 대비 제한적 타입 지원** |
| 84 | + - JsDoc만으로는 복잡한 타입(예: 제네릭, 유틸리티 타입 등)을 완벽하게 표현하기 어렵다. |
| 85 | + |
| 86 | +2. **주석 유지보수 필요** |
| 87 | + - 코드가 변경될 때 주석도 함께 관리해야 하므로 유지보수 부담이 증가할 수 있다. |
| 88 | + |
| 89 | +3. **런타임 타입 검사가 없음** |
| 90 | + - JsDoc은 정적 분석을 도울 뿐, 실행 시점에서 타입 검사를 수행하지 않는다. |
| 91 | + |
| 92 | +4. **초기 학습 필요** |
| 93 | + - 다양한 태그와 문법을 익히는 과정이 필요하며, 적절한 활용을 위해 학습 시간이 필요하다. |
| 94 | + |
| 95 | +## Reference |
| 96 | + |
| 97 | +**link:** External reference` |
| 98 | +- [JsDoc 공식 문서](https://jsdoc.app/) |
0 commit comments