Где найти документацию по синтаксису комментариев в TypeScript?

Официальная документация и синтаксис комментариев в TypeScript

TypeScript не вводит собственного синтаксиса комментариев, отличного от JavaScript. Все комментарии в TypeScript — это стандартные JavaScript-комментарии. Однако есть важное дополнение: поддержка JSDoc-аннотаций, которые обрабатываются компилятором TypeScript для получения информации о типах. Официальная документация по комментариям находится в разделе "Supported JSDoc".

Типы комментариев в TypeScript

• Однострочные комментарии: // текст — игнорируются компилятором.
• Многострочные комментарии: /* текст */ — также игнорируются.
• JSDoc-комментарии: /** текст */ — специальный формат, который TypeScript анализирует для вывода типов, документации и подсказок в IDE.

Как работают JSDoc-комментарии в TypeScript

TypeScript поддерживает большинство тегов JSDoc, таких как @param, @returns, @type, @template и другие. Компилятор использует их для типизации, когда вы не указываете типы явно. Например:

/**
 * Складывает два числа.
 * @param {number} a - Первое число
 * @param {number} b - Второе число
 * @returns {number} Сумма a и b
 */
function add(a, b) {
    return a + b;
}

TypeScript выведет типы a: number, b: number и возвращаемое значение number на основе JSDoc. Это особенно полезно, когда вы работаете с чистым JavaScript, но используете TypeScript для проверки (например, в файлах .js с // @ts-check).

Где искать документацию

• Официальный хендбук TypeScript: раздел "JSDoc Supported Types" — полный список поддерживаемых тегов.
• Спецификация JSDoc: jsdoc.app — оригинальная документация по JSDoc (но TypeScript поддерживает не всё).
• TypeScript Wiki на GitHub: часто содержит примеры использования JSDoc для типизации.

Примеры использования

// 1. Просто комментарий
const name: string = "TypeScript"; // это тоже комментарий

/* 2. Многострочный
   комментарий */
const version: number = 5.0;

/**
 * 3. JSDoc для документирования функции
 * @param value - Значение для проверки
 * @returns true, если value — строка
 */
function isString(value: unknown): boolean {
    return typeof value === "string";
}

/**
 * 4. JSDoc для описания типа переменной
 * @type {{ id: number; name: string }}
 */
const user = { id: 1, name: "Alice" };

Важные моменты

• TypeScript не требует JSDoc, если вы используете явные аннотации типов (например, function add(a: number, b: number): number).
• JSDoc-комментарии в .ts файлах обычно избыточны, если типы уже указаны, но полезны для генерации документации.
• Для .js файлов с проверкой TypeScript JSDoc — основной способ типизации.

Таким образом, весь синтаксис комментариев TypeScript — это стандартный JavaScript + JSDoc. Никакого отдельного "TypeScript-синтаксиса" для комментариев не существует.

/**
 * Создает новый массив, заполненный указанным значением.
 * 
 * @param length - Длина массива
 * @param value - Значение для заполнения
 * @returns Новый массив
 * 
 * @example
 * ```typescript
 * const arr = createArray(3, 'a');
 * // arr = ['a', 'a', 'a']
 * ```
 */
function createArray<T>(length: number, value: T): T[] {
    return new Array(length).fill(value);
}