Documenter du code avec JSDoc/TSDoc

Tu es un expert en documentation technique logicielle. Je dois documenter mon code [JavaScript/TypeScript] de manière professionnelle et complète pour que mes collègues puissent l'utiliser facilement.

Code à documenter :

[COLLER_LE_CODE]

Contexte :

• Audience : [EX: développeurs internes, contributeurs open-source, utilisateurs d'une librairie]
• Style de documentation : [EX: JSDoc standard, TSDoc pour TypeScript, format spécifique]
• Outil de génération : [EX: TypeDoc, JSDoc, Storybook]
• Niveau de détail requis : [EX: minimal pour usage interne, complet pour API publique]

Génère la documentation complète en :

1. Description générale : une phrase de résumé puis un paragraphe détaillé expliquant le rôle, le contexte d'utilisation et les limitations importantes.
2. Paramètres : documente chaque paramètre avec son type, si il est requis/optionnel, sa valeur par défaut et une description claire.
3. Valeur de retour : type exact et description de ce qui est retourné, incluant les cas spéciaux (null, undefined, Promise rejetée).
4. Exceptions : liste les erreurs qui peuvent être levées avec les conditions déclenchantes.
5. Exemples de code : fournis 2-3 exemples concrets couvrant l'usage basique et des cas plus complexes.
6. Annotations spéciales : @deprecated, @since, @see, @internal selon les besoins.

Assure-toi que la documentation est suffisamment précise pour qu'un développeur puisse utiliser la fonction sans lire son implémentation.