Ist die Syntax für TypeScript-Kommentare irgendwo dokumentiert?

Und unterstützt es jetzt zufällig das C # ///-System?

Die richtige Syntax wird jetzt von TSDoc verwendet . Auf diese Weise können Sie Ihre Kommentare von Visual Studio Code oder anderen Dokumentationstools verstehen lassen.

Eine gute Übersicht über die Syntax finden Sie hier und insbesondere hier . Die genaue Spezifikation sollte "bald" geschrieben werden .

Eine weitere Datei, die es wert ist, überprüft zu werden, ist diese, in der Sie nützliche Standard-Tags sehen.

Hinweis : Sie sollten JSDoc nicht verwenden, wie auf der TSDoc-Hauptseite erläutert: Warum kann JSDoc nicht der Standard sein? Leider ist die JSDoc-Grammatik nicht streng spezifiziert, sondern wird aus dem Verhalten einer bestimmten Implementierung abgeleitet. Die Mehrheit der Standard-JSDoc-Tags beschäftigt sich mit der Bereitstellung von Typanmerkungen für einfaches JavaScript, was für eine stark typisierte Sprache wie TypeScript irrelevant ist. TSDoc behebt diese Einschränkungen und befasst sich gleichzeitig mit komplexeren Zielen.

Zukunft

Das TypeScript-Team und andere Teams, an denen TypeScript beteiligt ist, planen die Erstellung einer formalen Standard-TSDoc-Spezifikation. Der 1.0.0Entwurf wurde noch nicht fertiggestellt: https://github.com/Microsoft/tsdoc#where-are-we-on-the-roadmap

Aktuell

TypeScript verwendet JSDoc. z.B

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

So lernen Sie jsdoc: https://jsdoc.app/

Sie müssen jedoch die Typanmerkungserweiterungen in JSDoc nicht verwenden.

Sie können (und sollten) weiterhin andere jsdoc- Block-Tags wie @returnsusw. verwenden.

Beispiel

Nur ein Beispiel. Konzentrieren Sie sich auf die Typen (nicht auf den Inhalt).

JSDoc-Version (Hinweisarten in Dokumenten):

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

TypeScript-Version (beachten Sie die Verlagerung der Typen):

/**
 * 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;
}

Sie können auch Informationen zu Parametern, Rückgaben usw. hinzufügen, indem Sie:

/**
* 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()
}

Dies führt dazu, dass Editoren wie VS Code dies wie folgt anzeigen:

Sie können Kommentare wie in normalem JavaScript verwenden:

Die TypeScript-Syntax ist eine Obermenge der Ecmascript 5 (ES5) -Syntax. [...]

Dieses Dokument beschreibt die von TypeScript hinzugefügte syntaktische Grammatik

Davon abgesehen habe ich dies nur über Kommentare in den Sprachspezifikationen gefunden:

TypeScript bietet JavaScript-Programmierern auch ein System optionaler Typanmerkungen . Diese Typanmerkungen ähneln den JSDoc-Kommentaren im Closure-System, sind jedoch in TypeScript direkt in die Sprachsyntax integriert. Diese Integration macht den Code besser lesbar und reduziert die Wartungskosten für die Synchronisierung von Typanmerkungen mit den entsprechenden Variablen.

11.1.1 Abhängigkeiten von Quelldateien:

Ein Kommentar des Formulars /// <reference path="..."/>fügt eine Abhängigkeit von der im Pfadargument angegebenen Quelldatei hinzu. Der Pfad wird relativ zum Verzeichnis der enthaltenen Quelldatei aufgelöst

Quelle:
https://github.com/Microsoft/TypeScript/blob/master/doc/spec.md

TypeScript ist daher eine strikte syntaktische Obermenge von JavaScript

• Einzeilige Kommentare beginnen mit //
• Mehrzeilige Kommentare beginnen mit / * und enden mit * /