Ответ 1

Правильный синтаксис теперь тот, который используется TSDoc. Это позволит вам понимать ваши комментарии с помощью кода Visual Studio или других инструментов документации.

Хороший обзор синтаксиса доступен здесь и особенно здесь. Точная спецификация должна быть "скоро" написана.

Другой файл, который стоит проверить, это тот, где вы увидите полезные стандартные теги.

Примечание: вы не должны использовать JSDoc, как объяснено на главной странице TSDoc: почему JSDoc не может быть стандартом? К сожалению, грамматика JSDoc не строго определена, а скорее выведена из поведения конкретной реализации. Большинство стандартных тегов JSDoc озабочены предоставлением аннотаций типов для простого JavaScript, что не имеет значения для строго типизированного языка, такого как TypeScript. TSDoc устраняет эти ограничения, а также решает более сложные задачи.

Ответ 2

TypeScript использует JSDoc. например

/** This is a description of the foo function. */
function foo() {
}

Чтобы узнать jsdoc: https://jsdoc.app/

Но вам не нужно использовать расширения аннотации типов в JSDoc.

Вы можете (и должны) по-прежнему использовать другие теги блока @returns такие как @returns и т.д.

пример

Просто пример. Сосредоточьтесь на типах (не содержание).

Версия JSDoc (типы уведомлений в документах):

/**
 * Returns the sum of a and b
 * @param {number} a
 * @param {number} b
 * @returns {number}
 */
function sum(a, b) {
    return a + b;
}

Версия TypeScript (обратите внимание на перестановку типов):

/**
 * Takes two numbers and returns their sum
 * @param a first input to sum
 * @param b second input to sum
 * @returns sum of a and b
 */
function sum(a: number, b: number): number {
    return a + b;
}

Ответ 3

Вы можете добавить информацию о параметрах, возвратах и т.д., Используя:

/**
* This is the foo function
* @param bar This is the bar parameter
* @returns returns a string version of bar
*/
function foo(bar: number): string {
    return bar.toString()
}

Это приведет к тому, что редакторы, такие как VS Code, отобразят его следующим образом:

Ответ 4

Вы можете использовать комментарии как в обычном JavaScript:

Синтаксис TypeScript - это расширенный набор синтаксиса Ecmascript 5 (ES5). [...]

Этот документ описывает синтаксическую грамматику, добавленную TypeScript

Кроме этого, я нашел это только о комментариях в спецификации языка:

TypeScript также предоставляет программистам JavaScript систему необязательных аннотаций типов. Эти аннотации типов похожи на комментарии JSDoc, найденные в системе Closure, но в TypeScript они интегрированы непосредственно в синтаксис языка. Эта интеграция делает код более читабельным и снижает затраты на обслуживание синхронизации аннотаций типов с соответствующими им переменными.

11.1.1 Зависимости исходных файлов:

Комментарий в форме ///<reference path="..."/> добавляет зависимость от исходного файла, указанного в аргументе пути. Путь разрешается относительно каталога, содержащего исходный файл

Источник:
https://github.com/Microsoft/TypeScript/blob/master/doc/spec.md

Ответ 5

TypeScript является строгим синтаксическим расширенным набором JavaScript, следовательно

• Однострочные комментарии начинаются с //
• Многострочные комментарии начинаются с /* и заканчиваются */