Czy składnia komentarzy TypeScript jest gdzieś udokumentowana?

I czy przypadkiem obsługuje teraz system C # ///?

Właściwa składnia jest teraz używana przez TSDoc . Umożliwi to zrozumienie komentarzy przez Visual Studio Code lub inne narzędzia dokumentacji.

Dobry przegląd składni jest dostępny tutaj, a zwłaszcza tutaj . Dokładna specyfikacja powinna zostać „wkrótce” spisana .

Kolejnym plikiem, który warto sprawdzić, jest ten, w którym zobaczysz przydatne standardowe tagi.

Uwaga : nie powinieneś używać JSDoc, jak wyjaśniono na stronie głównej TSDoc: Dlaczego JSDoc nie może być standardem? Niestety gramatyka JSDoc nie jest rygorystycznie określona, ​​ale raczej wywnioskowana na podstawie zachowania określonej implementacji. Większość standardowych tagów JSDoc zajmuje się dostarczaniem adnotacji typu dla zwykłego JavaScript, co jest nieistotnym problemem w przypadku języka silnie typizowanego, takiego jak TypeScript. TSDoc zajmuje się tymi ograniczeniami, jednocześnie zajmując się bardziej wyrafinowanym zestawem celów.

Przyszłość

Zespół TypeScript i inne zaangażowane zespoły TypeScript planują stworzyć standardową formalną specyfikację TSDoc. Wersja 1.0.0robocza nie została jeszcze sfinalizowana: https://github.com/Microsoft/tsdoc#where-are-we-on-the-roadmap

obecny

TypeScript używa JSDoc. na przykład

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

Aby nauczyć się jsdoc: https://jsdoc.app/

Ale nie musisz używać rozszerzeń adnotacji typu w JSDoc.

Możesz (i powinieneś) nadal używać innych tagów blokowych jsdoc , takich jak @returnsitp.

Przykład

Tylko przykład. Skoncentruj się na typach (nie na treści).

Wersja JSDoc (typy powiadomień w dokumentach):

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

Wersja TypeScript (zwróć uwagę na zmianę lokalizacji typów):

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

Możesz również dodać informacje o parametrach, zwrotach itp. Za pomocą:

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

Spowoduje to, że edytory, takie jak VS Code, wyświetlą go w następujący sposób:

Możesz używać komentarzy jak w zwykłym JavaScript:

Składnia TypeScript jest nadzbiorem składni Ecmascript 5 (ES5). […]

W tym dokumencie opisano gramatykę składni dodaną przez TypeScript

Poza tym znalazłem tylko to o komentarzach w specyfikacji języka:

TypeScript udostępnia również programistom JavaScript system opcjonalnych adnotacji typu . Te adnotacje typu są jak komentarze JSDoc znalezione w systemie Closure, ale w TypeScript są zintegrowane bezpośrednio ze składnią języka. Ta integracja sprawia, że ​​kod jest bardziej czytelny i zmniejsza koszty utrzymania synchronizacji adnotacji typu z odpowiadającymi im zmiennymi.

11.1.1 Zależności plików źródłowych:

Komentarz formularza /// <reference path="..."/>dodaje zależność od pliku źródłowego określonego w argumencie ścieżka. Ścieżka jest rozpoznawana względem katalogu zawierającego plik źródłowy

Źródło:
https://github.com/Microsoft/TypeScript/blob/master/doc/spec.md

TypeScript jest więc ścisłym nadzbiorem składniowym języka JavaScript

• Komentarze jednowierszowe zaczynają się od //
• Komentarze wielowierszowe zaczynają się od / * i kończą na * /