Documentation de composant OO

Créez une nouvelle documentation pour un composant orienté objet ou mettez à jour un fichier de documentation existant en analysant l'implémentation actuelle.

Déterminez d'abord le mode

Choisissez le flux de travail avant d'écrire quoi que ce soit :

1. Utilisez le mode mise à jour quand l'utilisateur fournit un fichier Markdown de documentation existant, pointe vers un chemin docs, ou demande explicitement d'actualiser ou de réviser la documentation existante. Suivez references/update-mode.md.
2. Utilisez le mode création quand l'utilisateur fournit un fichier ou dossier source, pointe vers un chemin de composant, ou demande de générer la documentation à partir du code. Suivez references/create-mode.md.
3. Si à la fois du code et un fichier de documentation existant sont fournis, traitez le fichier de documentation existant comme la cible de sortie et utilisez le code source actuel comme source de vérité.
4. Si la demande est ambiguë, déduisez le mode à partir du type de chemin quand possible : un fichier de documentation Markdown existant signifie le mode mise à jour ; un chemin source/composant signifie le mode création.

Standards de documentation

• DOC-001 : Suivez les niveaux de documentation du modèle C4 (Contexte, Conteneurs, Composants, Code)
• DOC-002 : Alignez-vous avec le modèle de documentation d'architecture logicielle Arc42
• DOC-003 : Respectez la norme IEEE 1016 Software Design Description
• DOC-004 : Appliquez les principes de documentation Agile (juste assez de documentation qui ajoute de la valeur)
• DOC-005 : Ciblez les développeurs et mainteneurs comme public principal

Guidance d'analyse partagée

• ANA-001 : Déterminez la limite du composant principal et si l'entrée représente un dossier, un fichier ou une cible de documentation existante
• ANA-002 : Examinez les fichiers de code source pour les structures de classe, l'héritage, la composition et les interfaces
• ANA-003 : Identifiez les patterns de conception, les décisions architecturales et les points d'intégration
• ANA-004 : Documentez ou actualisez les API publiques, interfaces, dépendances et patterns d'utilisation
• ANA-005 : Capturez les paramètres de méthode, valeurs de retour, comportement asynchrone, exceptions et préoccupations de cycle de vie
• ANA-006 : Évaluez les caractéristiques de performance, sécurité, fiabilité, maintenabilité et extensibilité
• ANA-007 : Déduisez le flux de données, les patterns de collaboration et les relations avec les composants environnants
• ANA-008 : Gardez la documentation ancrée dans l'implémentation ; évitez d'inventer un comportement qui n'est pas soutenu par le code

Exigences de sortie partagées

• Utilisez assets/documentation-template.md comme liste de sections canoniques et structure de base.
• Conservez la sortie en Markdown avec une hiérarchie d'en-têtes claire, des tableaux où utiles, des blocs de code pour les exemples et des diagrammes Mermaid quand les relations d'architecture doivent être visualisées.
• Faites en sorte que les exemples et descriptions d'interface correspondent à l'implémentation actuelle plutôt qu'à des espaces réservés génériques.
• Incluez uniquement les informations qui peuvent être soutenues par le code, la structure du projet, la configuration ou des hypothèses clairement énoncées.
• Quand la couverture source est incomplète, documentez la limitation explicitement au lieu de deviner.

Optimisations spécifiques au langage

• LNG-001 : C#/.NET - async/await, injection de dépendances, configuration, disposal, patterns d'options
• LNG-002 : Java - framework Spring, annotations, gestion d'exceptions, packaging, injection de dépendances
• LNG-003 : TypeScript/JavaScript - modules, patterns asynchrones, types, dépendances npm, frontières d'exécution
• LNG-004 : Python - packages, environnements virtuels, type hints, tests, gestion de dépendances

Gestion des erreurs

• ERR-001 : Si le chemin n'existe pas, expliquez quel chemin était attendu et si le skill a besoin d'un chemin source ou d'un fichier de documentation existant
• ERR-002 : Si aucun fichier source pertinent n'est trouvé, documentez l'écart et suggérez les emplacements probables à inspecter ensuite
• ERR-003 : Si la cible de documentation ne peut pas être déduite de la demande, énoncez l'ambiguïté et demandez uniquement le chemin manquant quand l'inférence n'est pas possible
• ERR-004 : Si le code utilise des patterns architecturaux non standards, documentez l'approche personnalisée plutôt que de la forcer dans un pattern générique
• ERR-005 : Si l'accès source est incomplet, continuez avec les éléments de preuve disponibles et signalez clairement toute section non supportée

Flux de travail

1. Déterminez si la tâche est en mode création ou en mode mise à jour.
2. Inspectez l'implémentation du composant et tous les fichiers connexes nécessaires pour comprendre sa surface publique et sa structure interne.
3. Utilisez assets/documentation-template.md comme échafaudage de documentation partagé.
4. Appliquez les règles spécifiques au mode dans references/create-mode.md ou references/update-mode.md.
5. Produisez ou révisez la documentation afin que les diagrammes, exemples, interfaces, dépendances et attributs de qualité reflètent l'implémentation actuelle.

Critères d'achèvement

• La documentation identifie clairement l'objectif du composant, l'architecture, les interfaces, les détails d'implémentation, les patterns d'utilisation, les attributs de qualité et les références.
• Les champs de frontmatter sont précis pour le mode sélectionné.
• Les exemples et diagrammes correspondent à l'implémentation.
• Toute inconnue, écart ou hypothèse est explicitement signalé.