Où la syntaxe des commentaires TypeScript est-elle documentée?
La syntaxe des commentaires TypeScript est-elle documentée quelque part?
Et par hasard, supporte-t-il maintenant le système C # ///?
La bonne syntaxe est maintenant celle utilisée par TSDoc . Cela vous permettra de faire comprendre vos commentaires à 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 "bientôt" écrite .
Un autre fichier intéressant est celui-ci où vous verrez des balises standard utiles.
Remarque : vous ne devez pas utiliser JSDoc, comme expliqué à la page principale TSDoc: Pourquoi JSDoc ne peut-il pas être la norme? Malheureusement, la grammaire JSDoc n’est pas rigoureusement spécifiée, mais déduite du comportement d’une implémentation particulière. La majorité des balises JSDoc standard sont soucieuses de fournir des annotations de type pour JavaScript, ce qui est une préoccupation non pertinente pour un langage fortement typé tel que TypeScript. TSDoc résout ces problèmes tout en abordant un ensemble d'objectifs plus sophistiqués.
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) continuer à utiliser d’autres balises de bloc jsdoc telles que @returns etc.
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 déplacement 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 ajouter des informations sur les paramètres, les retours, etc., ainsi:
/**
* 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()
}
Les éditeurs comme VS Code l’afficheront ainsi:
Vous pouvez utiliser des commentaires comme en JavaScript normal:
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é ceci que dans les commentaires de langue:
TypeScript fournit également aux programmeurs JavaScript un système d’annotations de type facultatives . Ces annotations de type ressemblent aux commentaires JSDoc trouvés dans le système Closure, mais ils sont directement intégrés à TypeScript dans la syntaxe du langage. Cette intégration rend le code plus lisible et réduit les coûts de maintenance liés à la synchronisation des annotations de type avec les variables correspondantes.
11.1.1 Dépendances des fichiers sources:
Un commentaire de la forme
/// <reference path="..."/>ajoute une dépendance au fichier source spécifié dans l'argument path. Le chemin est résolu par rapport au répertoire du fichier source contenant
La 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 multi-lignes commencent par/* et se terminent par * /