Чи документований синтаксис коментарів TypeScript де-небудь?

І випадково, чи підтримує вона зараз систему C # ///?

Зараз правильний синтаксис використовується тим, що використовується TSDoc . Це дозволить зрозуміти ваші коментарі кодом Visual Studio або іншими інструментами документації.

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

Ще один файл, який варто перевірити, це цей файл, де ви побачите корисні стандартні теги.

Примітка . Ви не повинні використовувати JSDoc, як пояснено на головній сторінці TSDoc: Чому JSDoc не може бути стандартом? На жаль, граматика JSDoc не є чітко визначеною, а досить випливає з поведінки конкретної реалізації. Більшість стандартних тегів JSDoc зайняті наданням анотацій типів для простого JavaScript, що не викликає занепокоєння для сильно набраної мови, наприклад TypeScript. TSDoc вирішує ці обмеження, одночасно вирішуючи складніший набір цілей.

Майбутнє

Команда TypeScript та інші команди, що займаються TypeScript, планують створити стандартну формальну специфікацію TSDoc. 1.0.0Проект не був завершений ще: https://github.com/Microsoft/tsdoc#where-are-we-on-the-roadmap

Поточний

TypeScript використовує JSDoc. напр

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

Щоб дізнатися jsdoc: https://jsdoc.app/

Але вам не потрібно використовувати розширення анотацій типу в JSDoc.

Ви все ще можете (і повинні) використовувати інші теги блоків jsdoc, наприклад @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;
}

Ви можете додати інформацію про параметри, повернення тощо, а також, використовуючи:

/**
* 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, відображатимуть його як таке:

Ви можете використовувати коментарі, як у звичайному JavaScript:

Синтаксис TypeScript - це набір синтаксису Ecmascript 5 (ES5). [...]

Цей документ описує синтаксичну граматику, додану TypeScript

Окрім цього, я знайшов це лише щодо коментарів у мовних специфікаціях:

TypeScript також надає програмістам JavaScript систему необов'язкових анотацій типу . Ці типові анотації схожі на коментарі JSDoc, знайдені в системі закриття, але в TypeScript вони інтегруються безпосередньо в синтаксис мови. Ця інтеграція робить код більш читабельним і зменшує вартість обслуговування синхронізації анотацій типу із відповідними змінними.

11.1.1 Залежності файлів джерела:

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

Джерело:
https://github.com/Microsoft/TypeScript/blob/master/doc/spec.md

TypeScript - це суворий синтаксичний набір JavaScript, отже

• Однорядкові коментарі починаються з //
• Багаторядкові коментарі починаються з / * і закінчуються * /