Is de syntaxis voor TypeScript-opmerkingen ergens gedocumenteerd?
En ondersteunt het nu toevallig het C# ///-systeem?
Antwoord 1, autoriteit 100%
Toekomst
Het TypeScript-team en andere bij TypeScript betrokken teams zijn van plan om een standaard formele TSDoc-specificatie te maken. Het 1.0.0concept is nog niet afgerond: https://github.com/Microsoft/tsdoc#where-are-we-on-the-roadmap
Huidige
TypeScript gebruikt JSDoc. bijv.
/** This is a description of the foo function. */
function foo() {
}
Jsdoc leren: https://jsdoc.app/
Maar u hoeft de typeannotatie-extensies in JSDoc niet te gebruiken.
Je kunt (en moet) nog steeds andere jsdoc block-tagsgebruiken, zoals @returnsenz.
Voorbeeld
Gewoon een voorbeeld. Focus op de typen (niet op de inhoud).
JSDoc-versie (type kennisgeving in documenten):
/**
* Returns the sum of a and b
* @param {number} a
* @param {number} b
* @returns {number}
*/
function sum(a, b) {
return a + b;
}
TypeScript-versie (let op de verplaatsing van typen):
/**
* 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;
}
Antwoord 2, autoriteit 46%
Update november 2020
Er is nu een website online met alle beschikbare TSDoc-syntaxis (en dat is geweldig): https://tsdoc.org/
Ter referentie, oud antwoord:
De juiste syntaxis wordt nu gebruikt door TSDoc. Hiermee kunt u uw opmerkingen laten begrijpen door Visual Studio Code of andere documentatietools.
Een goed overzicht van de syntaxis is hieren vooral hier. De precieze specificaties moeten “binnenkort” worden opgeschreven.
Een ander bestand dat het bekijken waard is, is dezewaar u handige standaardtags ziet.
Opmerking: je moet JSDoc niet gebruiken, zoals uitgelegd op de hoofdpagina van TSDoc: Waarom kan JSDoc niet de standaard zijn? Helaas is de JSDoc-grammatica niet strikt gespecificeerd, maar eerder afgeleid uit het gedrag van een bepaalde implementatie. De meeste standaard JSDoc-tags houden zich bezig met het leveren van typeannotaties voor gewoon JavaScript, wat een irrelevante zorg is voor een sterk getypeerde taal zoals TypeScript. TSDoc lost deze beperkingen op en pakt ook een meer geavanceerde reeks doelen aan.
Antwoord 3, autoriteit 31%
Je kunt ook informatie over parameters, retouren, etc. toevoegen met:
/**
* 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()
}
Dit zorgt ervoor dat editors zoals VS Code het als volgt weergeven:
Antwoord 4, autoriteit 7%
Je kunt opmerkingen gebruiken zoals in gewoon JavaScript:
[…] TypeScript-syntaxis is een superset van ECMAScript 2015 (ES2015)-syntaxis.
[…] Dit document beschrijft de syntactische grammatica toegevoegd door TypeScript […]
Bron: TypeScript-taalspecificatie
De enige twee vermeldingen van het woord “opmerkingen” in de specificaties zijn:
[…] TypeScript biedt JavaScript-programmeurs ook een systeem van optionele type-annotaties. Deze typeannotaties zijn vergelijkbaar met de JSDoc-opmerkingen in het Closure-systeem, maar in TypeScript zijn ze rechtstreeks geïntegreerd in de taalsyntaxis. Deze integratie maakt de code leesbaarder en verlaagt de onderhoudskosten van het synchroniseren van typeannotaties met de bijbehorende variabelen.
11.1.1 Afhankelijkheden van bronbestanden
[…] Een opmerking van de vorm
/// <reference path="..."/>voegt een afhankelijkheid toe aan het bronbestand
opgegeven in het padargument. Het pad is opgelost ten opzichte van de map van het bronbestand dat erin staat.
Antwoord 5
TypeScript is een strikte syntactische superset van JavaScript, vandaar
- Opmerkingen in één regel beginnen met //
- Opmerkingen met meerdere regels beginnen met /* en eindigen met */