TypeScript 주석: JSDoc, @ts-ignore, @ts-expect-error

TypeScript 주석은 JavaScript 주석입니다. //는 줄의 나머지를, /* */는 블록을 주석으로 만듭니다. /**로 시작하는 블록 주석은 문서화 주석(JSDoc)이며, 문서화 대상 위에 마우스를 올리면 에디터가 보여 줍니다. 여기에 더해 TypeScript는 컴파일러가 코드를 검사하는 방식을 바꾸는 특수 주석 몇 가지를 읽습니다.

// A single-line comment runs to the end of the line.

/*
  A block comment can span
  several lines.
*/

/**
 * Converts a temperature from Celsius to Fahrenheit.
 * @param celsius Degrees Celsius.
 * @returns Degrees Fahrenheit.
 */
function toFahrenheit(celsius: number): number {
    return (celsius * 9) / 5 + 32; // a comment after code
}

console.log(toFahrenheit(100)); /* inline block comment */ // 212

출력:

212

주석은 프로그램에 영향을 주지 않습니다. 아래에서 다룰 지시문 주석을 빼면 타입 검사에도 영향을 주지 않습니다.

한 줄 주석과 블록 주석

//는 그 줄에서 뒤에 오는 모든 것을 주석으로 만들며, 코드 한 줄을 빠르게 끄는 방법이기도 합니다. /* */는 줄 중간에 올 수도 있고 여러 줄을 덮을 수도 있습니다.

블록 주석은 중첩되지 않습니다. 첫 번째 */에서 주석이 끝나므로, 이미 블록 주석이 들어 있는 코드를 감싸면 깨집니다.

/* outer comment /* inner comment */ this text is now code */

그러면 컴파일러는 this text is now code */를 코드로 읽으려다 문법 오류를 보고합니다. 블록 주석이 들어 있는 영역을 주석 처리하려면 줄마다 //를 쓰세요. 대부분의 에디터에서는 Ctrl+/(macOS에서는 Cmd+/)로 할 수 있습니다.

JSDoc 문서화 주석

함수, 클래스, 메서드, 속성, 인터페이스, 변수 바로 앞의 /** ... */ 주석이 그 대상을 문서화합니다. 에디터는 이 텍스트를 마우스를 올렸을 때의 툴팁과 자동 완성에 보여 주고, TypeDoc 같은 문서 생성기는 이를 레퍼런스 페이지로 만듭니다. Microsoft가 시작한 TypeScript 코드용 주석 표준인 TSDoc도 흔한 태그에는 같은 문법을 씁니다.

.ts 파일에서는 JSDoc에 타입을 반복하지 마세요. 코드의 타입 표기가 곧 타입이고, 거기서 JSDoc 타입 태그는 무시됩니다. /** @type {string} */ const v: number = 5;는 : number만 인정되므로 아무 불평 없이 컴파일됩니다.

interface Account {
    /** Balance in cents, to avoid floating-point rounding. */
    balance: number;
}

/**
 * Moves money between two accounts.
 * @param from The account to take the money from.
 * @param to The account that receives it.
 * @param cents Amount in cents. Must not exceed `from.balance`.
 * @throws {RangeError} If the balance is too low.
 */
function transfer(from: Account, to: Account, cents: number): void {
    if (cents > from.balance) {
        throw new RangeError("insufficient funds");
    }
    from.balance -= cents;
    to.balance += cents;
}

const a: Account = { balance: 5000 };
const b: Account = { balance: 0 };
transfer(a, b, 1250);
console.log(a.balance, b.balance); // 3750 1250

에디터에서는 프로젝트 어디에서든 transfer나 balance 위에 마우스를 올리면 이 설명이 보입니다.

코드를 폐기 예정으로 표시하기

@deprecated는 컴파일 오류를 일으키지 않습니다. 대신 폐기 예정 함수를 쓰는 모든 곳을 취소선으로 표시하고 마우스를 올리면 이유를 보여 주라고 에디터에 알립니다. 호출하는 쪽을 대체 함수로 부드럽게 이끄는 방법입니다.

/** @deprecated Use {@link formatPrice} instead. It ignores the currency. */
function price(cents: number): string {
    return "$" + (cents / 100).toFixed(2);
}

function formatPrice(cents: number, currency: string): string {
    return `${(cents / 100).toFixed(2)} ${currency}`;
}

console.log(price(1999));              // still compiles and runs
console.log(formatPrice(1999, "EUR"));

출력:

$19.99
19.99 EUR

@ts-expect-error와 @ts-ignore

이 두 주석은 다음 줄의 타입 오류를 숨깁니다. 그것이 옳은 선택일 때도 있습니다. 함수가 잘못된 입력을 런타임에 어떻게 처리하는지 확인하는 테스트나, 라이브러리 타입에 알려진 빈틈이 있을 때가 그렇습니다.

function shout(text: string): string {
    return text.toUpperCase();
}

try {
    // @ts-expect-error: testing what happens when JavaScript callers pass a number
    shout(42);
} catch (e) {
    if (e instanceof Error) {
        console.log("runtime error:", e.message);
    }
}

출력:

runtime error: text.toUpperCase is not a function

주석이 없으면 shout(42)는 컴파일 오류(TS2345)입니다. 주석이 있으면 파일이 컴파일되고 호출이 런타임까지 도달하며, 그것이 이 테스트의 목적입니다.

두 지시문의 차이는 오류가 사라질 때 드러납니다. @ts-expect-error는 숨길 오류가 있어야 한다고 고집하므로, 쓸모없어진 주석은 그 자체가 오류가 됩니다.

// This does not compile: the line below has no type error to suppress.
function shout(text: string): string {
    return text.toUpperCase();
}

// @ts-expect-error
console.log(shout("fixed"));

index.ts(6,1): error TS2578: Unused '@ts-expect-error' directive.

같은 자리의 // @ts-ignore는 오류가 있을 때도, 사라진 뒤에도 조용합니다. 그래서 @ts-expect-error가 더 나은 기본값입니다. 누군가 타입을 고치면 억제 주석을 지워도 된다고 컴파일러가 알려 주기 때문입니다. 위 예제처럼 지시문 뒤에는 항상 이유를 적어서, 다음에 읽는 사람이 왜 거기 있는지 알게 하세요.

둘 다 다음 줄과 그 줄의 모든 오류에만 적용됩니다. 값 전체를 우회해야 한다면, 억제 주석보다 명시적인 as unknown as T나 런타임 검사가 대개 더 명확합니다.

@ts-nocheck와 @ts-check

파일 맨 위의 // @ts-nocheck는 그 파일 전체의 타입 검사를 끕니다. 어떤 코드보다도 먼저 와야 합니다. 더 아래에 두면 무시되고 오류가 그대로 나타납니다.

// @ts-nocheck
const n: number = "not a number"; // no error reported

대규모 JavaScript 코드베이스를 옮기는 동안에는 유용하지만, 그 밖의 경우라면 좋지 않은 신호입니다.

// @ts-check는 JavaScript 파일에서 반대로 동작합니다. tsconfig.json에서 checkJs가 꺼져 있어도 그 .js 파일에 대해 추론과 JSDoc 타입을 이용한 타입 검사를 켭니다(파일은 여전히 allowJs를 통해 프로젝트에 속해야 합니다).

// @ts-check

/**
 * @param {number} cents
 * @returns {string}
 */
function formatCents(cents) {
    return (cents / 100).toFixed(2);
}

formatCents("12"); // error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'.

JavaScript 파일에서는 JSDoc 태그가 곧 타입이며, 많은 프로젝트가 파일을 .ts로 바꾸지 않고도 이렇게 타입 검사를 받습니다.

트리플 슬래시 지시문

파일 맨 위에 있는 /// <reference ... /> 형태의 주석은 컴파일러 지시문입니다.

/// <reference types="node" />
/// <reference lib="es2023.array" />
/// <reference path="./globals.d.ts" />

• types="node"는 tsconfig.json의 "types"에 나열하는 것처럼 @types 패키지를 프로그램에 추가합니다.
• lib="..."는 lib 옵션처럼 내장 라이브러리를 프로그램에 추가합니다.
• path="..."는 다른 파일을 포함하며, 주로 .d.ts 파일 안에서 씁니다.

애플리케이션 코드에서는 import 문과 tsconfig.json 설정이 거의 모든 용도를 대신합니다. 이 지시문은 주로 선언 파일이나 Vite의 vite-env.d.ts 같은 생성된 코드에서 만납니다. 간단한 예로, lib를 쓰면 이 파일에서 더 새로운 배열 메서드를 쓸 수 있습니다.

/// <reference lib="es2023.array" />

const scores = [72, 95, 88];
const ranked = scores.toSorted((a, b) => b - a); // ES2023, copies instead of sorting in place

console.log(ranked); // [ 95, 88, 72 ]
console.log(scores); // [ 72, 95, 88 ]

컴파일된 출력의 주석

tsc는 자신이 쓰는 JavaScript에 주석을 남깁니다. 주석을 지우려면 "removeComments": true를 설정하세요. 그래도 /*!로 시작하는 주석은 남는데, 라이선스 헤더에 쓰는 관례입니다.

/*! MyLib v1.2.0 | MIT License */

declaration이 켜져 있으면 JSDoc 주석은 .d.ts 파일에도 복사되므로, 라이브러리 사용자는 에디터에서 설명을 볼 수 있습니다.