Používání JSDoc v TypeScriptu (bonus „automatická” dokumentace)

Jen nástin používání typů při programování v JavaScriptu a přitom stále těžit z výhod TypeScriptu.

---

V tomto příspěvku se zaměříme na koexistenci JavaScriptu s JSDoc a TypeScriptu. Projekty není totiž přímo nutné psát v TypeScriptu, při použití typického editoru (např. VSCode) totiž získáme i zabudovanou kontrolu JavaScriptu.

Většina knihoven totiž nabízí deklarační soubory *.d.ts, s jejichž pomocí editor dokáže kontrolovat používání knihoven. Pro vlastní kód pak můžeme použít část JSDoc syntaxe.

JSDoc v TypeScriptu

Podpora JSDoc v TypeScriptu umožňuje dokumentovat kód za použití standardních JSDoc anotací. Více informací o podporovaných typech a syntaxi lze nalézt v TypeScript: Documentation - JSDocReference.

Generování dokumentace z TypeScriptu

Můžete použít gulp spolu s jsdoc-to-md pro generování dokumentace z JSDoc.

Bohužel, osobně jsem spokojenější s typedoc-plugin-markdown. Nainstalovat lze pomocí npm install --save-dev gulp-typedoc typedoc typedoc-plugin-markdown, odkazy ke studiu:

• rogierschouten/gulp-typedoc: Gulp plugin for the typedoc TypeScript documentation tool.
• typedoc-plugin-markdown/packages/typedoc-plugin-markdown at master · tgreyuk/typedoc-plugin-markdown

Pro knihovny tedy nakonec píšu JavaScript & d.ts. Pro používání JSDoc & jsdoc-to-md zkouším konverzi…

Rozšíření JSDoc pro TypeScript

Existují různá rozšíření JSDoc pro lepší podporu TypeScriptu, jako například jsdoc-advanced-types-plugin a jsdoc-typescript-plugin, které umožňují generování TypeScript definic (.d.ts) z JSDoc anotovaného zdrojového kódu.

Důvody pro ne-migraci JavaScriptu na TypeScript

I přesto, že TypeScript nabízí mnoho výhod oproti klasickému JavaScriptu, existují i důvody proč některé projekty raději zůstávají u JavaScriptu. Článek One Reason not to migrate JavaScript to TypeScript | Nerd For Tech se zabývá některými z těchto důvodů.