La sintassi dei commenti TypeScript è documentata ovunque?

E per caso, ora supporta il ///sistema C # ?

La sintassi corretta è ora quella utilizzata da TSDoc . Ti consentirà di comprendere i tuoi commenti tramite Visual Studio Code o altri strumenti di documentazione.

Una buona panoramica della sintassi è disponibile qui e soprattutto qui . Le specifiche precise dovrebbero essere "presto" redatte .

Un altro file che vale la pena dare un'occhiata è questo in cui vedrai utili tag standard.

Nota : non dovresti usare JSDoc, come spiegato nella pagina principale di TSDoc: Perché JSDoc non può essere lo standard? Sfortunatamente, la grammatica di JSDoc non è specificata rigorosamente, ma piuttosto dedotta dal comportamento di una particolare implementazione. La maggior parte dei tag JSDoc standard si preoccupa di fornire annotazioni di tipo per JavaScript semplice, il che è una preoccupazione irrilevante per un linguaggio fortemente tipizzato come TypeScript. TSDoc affronta queste limitazioni affrontando al contempo una serie di obiettivi più sofisticati.

Futuro

Il team di TypeScript e altri team coinvolti di TypeScript hanno in programma di creare una specifica TSDoc formale standard. La 1.0.0bozza non è stata ancora finalizzata: https://github.com/Microsoft/tsdoc#where-are-we-on-the-roadmap

attuale

TypeScript utilizza JSDoc. per esempio

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

Per imparare jsdoc: https://jsdoc.app/

Ma non è necessario utilizzare le estensioni di annotazione del tipo in JSDoc.

Puoi (e dovresti) usare ancora altri tag di blocco jsdoc come @returnsecc.

Esempio

Solo un esempio Concentrati sui tipi (non sul contenuto).

Versione JSDoc (tipi di avviso nei documenti):

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

Versione TypeScript (notare la nuova posizione dei tipi):

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

Puoi aggiungere informazioni su parametri, ritorni, ecc. Anche usando:

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

Ciò farà sì che editor come VS Code lo visualizzino come segue:

Puoi usare commenti come nel normale JavaScript:

La sintassi TypeScript è un superset della sintassi Ecmascript 5 (ES5). [...]

Questo documento descrive la grammatica sintattica aggiunta da TypeScript

A parte questo, ho trovato questo solo sui commenti nelle specifiche della lingua:

TypeScript fornisce inoltre ai programmatori JavaScript un sistema di annotazioni di tipo opzionali . Queste annotazioni di tipo sono come i commenti JSDoc trovati nel sistema di chiusura, ma in TypeScript sono integrati direttamente nella sintassi del linguaggio. Questa integrazione rende il codice più leggibile e riduce i costi di manutenzione della sincronizzazione delle annotazioni dei tipi con le variabili corrispondenti.

11.1.1 Dipendenze dei file di origine:

Un commento del modulo /// <reference path="..."/>aggiunge una dipendenza dal file di origine specificato nell'argomento path. Il percorso viene risolto rispetto alla directory del file sorgente contenente

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

TypeScript è quindi un superset sintattico rigoroso di JavaScript

• I commenti a riga singola iniziano con //
• I commenti su più righe iniziano con / * e terminano con * /