Initial commit

2025-11-30 08:27:15 +08:00
commit e4ba6b249f
4 changed files with 177 additions and 0 deletions
--- a/skills/jsdoc-generator/SKILL.md
+++ b/skills/jsdoc-generator/SKILL.md
@@ -0,0 +1,117 @@
+---
+name: generating-jsdoc
+description: Automatically generates JSDoc documentation for ES6 modules with @param, @returns, @throws and examples. Use when adding functions, refactoring, or improving documentation
+allowed-tools: Read, Write, Grep, Glob, Bash
+---
+
+# Générateur JSDoc
+
+Génère documentation JSDoc pour modules ES6 (functions, classes, exports).
+
+## Table des matières
+
+- [Quand utiliser](#quand-utiliser)
+- [Scripts npm](#scripts-npm)
+- [Format JSDoc essentiel](#format-jsdoc-essentiel)
+- [Patterns projet](#patterns-projet)
+- [Workflow](#workflow)
+- [Checklist](#checklist)
+- [En cas de doute](#en-cas-de-doute)
+
+## Quand utiliser
+
+- Ajout fonctions ou classes
+- Refactoring code
+- Amélioration documentation
+- Avant release
+- Onboarding développeurs
+
+## Scripts npm
+
+- `npm run analyze:jsdoc` - Couverture JSDoc
+- `npm run improve:jsdoc` - Améliorer documentation
+- JSDoc HTML generation (si configuré)
+
+## Format JSDoc essentiel
+
+**Fonction :**
+
+```javascript
+/**
+ * Description brève (impératif : "Calcule", pas "Cette fonction")
+ *
+ * @param {Type} paramName - Description
+ * @param {Type} paramName2 - Description
+ * @returns {Type} Description retour
+ * @throws {ErrorType} Conditions erreur
+ * @example
+ * functionName(value1, value2); // → result
+ */
+```
+
+**Classe :**
+
+```javascript
+/**
+ * Description classe
+ * @class
+ * @extends ParentClass
+ */
+export class ClassName {}
+```
+
+**Types :** `string`, `number`, `boolean`, `Array<Type>`, `{key: Type}`, `Promise<Type>`, `Type1|Type2`
+
+## Patterns projet
+
+**Priorités :**
+
+- Haute : API publiques, fonctions complexes, classes
+- Moyenne : Méthodes, callbacks, utilitaires
+- Basse : Fonctions privées simples, getters évidents
+
+**Tags spéciaux :**
+
+- `@typedef` - Définir types complexes
+- `@fires` - Événements émis
+- `@deprecated` - Code obsolète
+- `@see {@link Name}` - Références croisées
+
+Examine code existant (modes, utils, core) pour patterns.
+
+## Workflow
+
+1. **Analyser :** `npm run analyze:jsdoc` → Identifier gaps
+2. **Documenter :** Description + @param + @returns + @example
+3. **Enrichir :** Cas limites, erreurs (@throws)
+4. **Vérifier :** Code cohérent, types précis, exemples du domaine
+
+## Checklist
+
+- [ ] Description brève et impérative
+- [ ] @param pour chaque paramètre avec type précis
+- [ ] @returns avec type et description
+- [ ] @throws si erreurs possibles
+- [ ] @example (au moins 1 cas réaliste)
+- [ ] @typedef pour types complexes
+- [ ] Types précis (pas {Object} générique)
+- [ ] Exemples avec valeurs du domaine
+- [ ] Cas limites documentés (null, undefined)
+- [ ] Cohérent avec reste projet
+
+## En cas de doute
+
+**Règles absolues :**
+
+1. Description impérative (imperative mood)
+2. Types explicites (jamais {\*} sauf dernier recours)
+3. Exemples du domaine (réalistes)
+4. @example obligatoire pour API publiques
+5. Maintenir à jour avec refactoring
+
+**Références :**
+
+- Code existant patterns (modes, utils)
+- `npm run analyze:jsdoc` - Vérifier couverture
+- JSDoc.app - Syntaxe spécifique
+- Examiner fichiers bien documentés du projet