Gdzie jest udokumentowana składnia komentarzy TypeScript?


165

Czy składnia komentarzy TypeScript jest gdzieś udokumentowana?

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

Odpowiedzi:


61

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.


177

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

wprowadź opis obrazu tutaj

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/

Próbny

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

1
Jak mówi Bas! Za dobry przykład wykorzystania sprawdzeniu jQuery.d.ts w DefinitelyTyped za
John Reilly

1
który oczywiście został jsdoc'ed przez @JohnnyReilly! :) github.com/borisyankov/DefinitelyTyped/blame/master/jquery/…
basarat

14
To nie jest dobra „najlepsza odpowiedź”, ponieważ nie wyjaśnia parametrów, właściwości i zwracanych wartości.
Piranha


5
To nie jest już aktualne. Zobacz zaktualizowaną odpowiedź poniżej.
Qortex

59

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:

wprowadź opis obrazu tutaj


1
Czy znasz klawisz skrótu do tego w VSCODE
jet_choong

3
Jeśli zaczniesz pisać, /**a następnie naciśnij tabwiersz powyżej funkcji, vs-code pomoże Ci wypełnić komentarz JSDoc parametrami
Sharpiro

14

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


Link do źródła jest uszkodzony.
Pavlo

1
Zastąpiłem go linkiem do źródła specyfikacji na GitHub. Dostępne również jako dokumenty Word i PDF: github.com/Microsoft/TypeScript/tree/master/doc
CodeManX

3

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 * /
Korzystając z naszej strony potwierdzasz, że przeczytałeś(-aś) i rozumiesz nasze zasady używania plików cookie i zasady ochrony prywatności.
Licensed under cc by-sa 3.0 with attribution required.