La syntaxe des commentaires TypeScript est-elle documentée quelque part?

Et par hasard, prend-il désormais en charge le ///système C # ?

La bonne syntaxe est désormais celle utilisée par TSDoc . Il vous permettra de faire comprendre vos commentaires par Visual Studio Code ou d'autres outils de documentation.

Un bon aperçu de la syntaxe est disponible ici et surtout ici . La spécification précise devrait être rédigée «bientôt» .

Un autre fichier à vérifier est celui-ci où vous verrez des balises standard utiles.

Remarque : vous ne devez pas utiliser JSDoc, comme expliqué sur la page principale de TSDoc: Pourquoi JSDoc ne peut-il pas être le standard? Malheureusement, la grammaire JSDoc n'est pas rigoureusement spécifiée mais plutôt déduite du comportement d'une implémentation particulière. La majorité des balises JSDoc standard se préoccupent de fournir des annotations de type pour du JavaScript brut, ce qui n'est pas pertinent pour un langage fortement typé tel que TypeScript. TSDoc répond à ces limitations tout en s'attaquant à un ensemble d'objectifs plus sophistiqués.

Futur

L'équipe TypeScript et les autres équipes impliquées dans TypeScript prévoient de créer une spécification TSDoc formelle standard. Le 1.0.0projet n'a pas encore été finalisé: https://github.com/Microsoft/tsdoc#where-are-we-on-the-roadmap

Actuel

TypeScript utilise JSDoc. par exemple

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

Pour apprendre jsdoc: https://jsdoc.app/

Mais vous n'avez pas besoin d'utiliser les extensions d'annotation de type dans JSDoc.

Vous pouvez (et devriez) toujours utiliser d'autres balises de bloc jsdoc comme @returnsetc.

Exemple

Juste un exemple. Concentrez-vous sur les types (pas sur le contenu).

Version JSDoc (types d'avis dans la documentation):

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

Version TypeScript (notez le re-emplacement des types):

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

Vous pouvez également ajouter des informations sur les paramètres, les retours, etc. en utilisant:

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

Cela obligera les éditeurs comme VS Code à l'afficher comme suit:

Vous pouvez utiliser des commentaires comme dans JavaScript standard:

La syntaxe TypeScript est un sur-ensemble de la syntaxe Ecmascript 5 (ES5). [...]

Ce document décrit la grammaire syntaxique ajoutée par TypeScript

En dehors de cela, je n'ai trouvé cela qu'à propos des commentaires dans les spécifications linguistiques:

TypeScript fournit également aux programmeurs JavaScript un système d' annotations de type facultatives . Ces annotations de type sont comme les commentaires JSDoc trouvés dans le système Closure, mais dans TypeScript, elles sont directement intégrées dans la syntaxe du langage. Cette intégration rend le code plus lisible et réduit le coût de maintenance de la synchronisation des annotations de type avec leurs variables correspondantes.

11.1.1 Dépendances des fichiers sources:

Un commentaire du formulaire /// <reference path="..."/>ajoute une dépendance sur le fichier source spécifié dans l'argument de chemin. Le chemin est résolu par rapport au répertoire du fichier source contenant

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

TypeScript est un sur-ensemble syntaxique strict de JavaScript, d'où

• Les commentaires sur une seule ligne commencent par //
• Les commentaires sur plusieurs lignes commencent par / * et se terminent par * /