Où la syntaxe des commentaires TypeScript est-elle documentée?


166

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

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

Réponses:


61

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.


177

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

entrez la description de l'image ici

Actuel

TypeScript utilise JSDoc. par exemple

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

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

Démo

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

1
Comme le dit Bas! Pour un bon exemple d'utilisation, consultez jQuery.d.ts de DefinitelyTyped
John Reilly

1
qui bien sûr a été jsdoc'ed par @JohnnyReilly! :) github.com/borisyankov/DefinitelyTyped/blame/master/jquery/…
basarat

14
Ce n'est pas une bonne «meilleure réponse» car elle n'explique pas les paramètres, les propriétés et les valeurs de retour.
Piranha


5
Ce n'est plus à jour. Voir la réponse mise à jour ci-dessous.
Qortex

59

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:

entrez la description de l'image ici


1
Connaissez-vous la touche de raccourci pour cela dans VSCODE
jet_choong

3
Si vous commencez à taper /**puis appuyez tabsur une ligne au-dessus de la fonction, vs-code vous aide à remplir le commentaire JSDoc avec des paramètres
Sharpiro

14

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


Le lien source est rompu.
Pavlo

1
Remplacé par un lien vers la source des spécifications sur GitHub. Également disponible sous forme de documents Word et PDF: github.com/Microsoft/TypeScript/tree/master/doc
CodeManX

3

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 * /
En utilisant notre site, vous reconnaissez avoir lu et compris notre politique liée aux cookies et notre politique de confidentialité.
Licensed under cc by-sa 3.0 with attribution required.