¿La sintaxis de los comentarios de TypeScript está documentada en alguna parte?

Y por casualidad, ¿ahora es compatible con el ///sistema C # ?

La sintaxis correcta es ahora la utilizada por TSDoc . Le permitirá que sus comentarios sean entendidos por Visual Studio Code u otras herramientas de documentación.

Una buena descripción general de la sintaxis está disponible aquí y especialmente aquí . La especificación precisa debe escribirse "pronto" .

Otro archivo que vale la pena revisar es este, donde verá etiquetas estándar útiles.

Nota : no debe usar JSDoc, como se explica en la página principal de TSDoc: ¿Por qué JSDoc no puede ser el estándar? Desafortunadamente, la gramática JSDoc no se especifica rigurosamente, sino que se infiere del comportamiento de una implementación particular. La mayoría de las etiquetas JSDoc estándar están preocupadas por proporcionar anotaciones de tipo para JavaScript simple, lo que es una preocupación irrelevante para un lenguaje fuertemente tipado como TypeScript. TSDoc aborda estas limitaciones al tiempo que aborda un conjunto de objetivos más sofisticado.

Futuro

El equipo de TypeScript, y otros equipos involucrados en TypeScript, planean crear una especificación TSDoc formal estándar. El 1.0.0borrador aún no se ha finalizado: https://github.com/Microsoft/tsdoc#where-are-we-on-the-roadmap

Actual

TypeScript usa JSDoc. p.ej

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

Para aprender jsdoc: https://jsdoc.app/

Pero no necesita usar las extensiones de anotación de tipo en JSDoc.

Puede (y debe) seguir utilizando otras etiquetas de bloque jsdoc como @returnsetc.

Ejemplo

Solo un ejemplo. Concéntrese en los tipos (no en el contenido).

Versión JSDoc (tipos de aviso en documentos):

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

Versión de TypeScript (observe la reubicación de los tipos):

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

También puede agregar información sobre parámetros, devoluciones, etc. utilizando:

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

Esto hará que los editores como VS Code lo muestren de la siguiente manera:

Puede usar comentarios como en JavaScript normal:

La sintaxis de TypeScript es un superconjunto de la sintaxis de Ecmascript 5 (ES5). [...]

Este documento describe la gramática sintáctica agregada por TypeScript

Aparte de eso, solo encontré esto sobre los comentarios en las especificaciones del idioma:

TypeScript también proporciona a los programadores de JavaScript un sistema de anotaciones de tipo opcionales . Estas anotaciones de tipo son como los comentarios de JSDoc encontrados en el sistema Closure, pero en TypeScript están integrados directamente en la sintaxis del lenguaje. Esta integración hace que el código sea más legible y reduce el costo de mantenimiento de sincronizar anotaciones de tipo con sus variables correspondientes.

11.1.1 Dependencias de los archivos de origen:

Un comentario del formulario /// <reference path="..."/>agrega una dependencia en el archivo fuente especificado en el argumento de ruta. La ruta se resuelve en relación con el directorio del archivo fuente que contiene

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

TypeScript es un estricto superconjunto sintáctico de JavaScript, por lo tanto

• Los comentarios de una sola línea comienzan con //
• Los comentarios de varias líneas comienzan con / * y terminan con * /