jsdoc

Skill zawiera praktyczne wytyczne do pisania komentarzy JSDoc w projektach TypeScript. Skupia się na dokumentacji właściwości i opcji konfiguracyjnych, unikając powtarzania informacji już zawartych w typach. Definiuje minimalny zestaw tagów (@default, @example, @note, @deprecated), które rzeczywiście dodają wartość. Pomaga utrzymać spójny styl dokumentacji w całej bazie kodu, szczególnie przydatny przy generowaniu dokumentacji z kodu.

1. Umieść komentarz JSDoc bezpośrednio nad właściwością lub parametrem, który chcesz udokumentować. Zacznij od krótkiego opisu tego, co dana opcja robi, bez powtarzania informacji zawartych już w typie TypeScript. 2. Dodaj tag @default, jeśli właściwość ma wartość domyślną — na przykład @default 'dist' dla katalogu wyjściowego. 3. Użyj tagu @example, aby pokazać konkretny sposób użycia — szczególnie przydatne dla skomplikowanych API lub opcji, których przeznaczenie nie jest oczywiste. 4. Dodaj tag @note, jeśli istnieje ważne zastrzeżenie lub informacja, którą użytkownik powinien znać — na przykład @note May change in v2. 5. Oznacz przestarzałe opcje tagiem @deprecated wraz z sugestią, co użyć zamiast tego. Unikaj tagów @param, @returns, @type i @typedef — TypeScript już dostarcza tych informacji, a powtarzanie ich w JSDoc tylko zaśmieca dokumentację.