Générer la documentation du code inline à l’aide de GitHub Copilot

Effectué

La documentation pertinente de votre code crée un codebase plus lisible et plus facile à maintenir que les autres développeurs peuvent facilement comprendre et utiliser.

GitHub Copilot Chat peut vous aider à documenter le code rapidement, avec précision et de manière cohérente.

Chacune des fonctionnalités de GitHub Copilot suivantes peut être utilisée pour créer une documentation de code inline :

• Vue Conversation : utilisez l'affichage Conversation en mode Demande, Agent ou Plan.
• Conversation inline : utilisez une session de conversation inline pour documenter du code spécifique (classes, méthodes ou blocs de code) sans quitter l’éditeur.
• Actions intelligentes : exécutez la fonction intelligente de génération de documents pour expliquer le code sélectionné sans même avoir à rédiger une invite.

Générer la documentation de code en ligne à l’aide de la vue Conversation

L’affichage de la conversation peut être utilisé pour générer la documentation du code en ligne pour un projet, un fichier de code, une classe ou une méthode. Vous pouvez consulter la documentation suggérée et demander des mises à jour si nécessaire avant de mettre à jour le fichier de code.

Chacun des trois modes de la vue Chat (Demander, Agent et Planifier) permet de générer une documentation de code en ligne. Le coût d’utilisation du mode Agent est supérieur à celui des autres modes, ce qui peut être une considération.

Générer la documentation de code en ligne en utilisant la vue Conversation dans le mode Demander

Le mode Demander peut être utilisé pour évaluer votre code et suggérer la documentation du code inline pour les projets, classes ou méthodes. Vous pouvez consulter la documentation incluse suggérée et générer des mises à jour si nécessaire avant d’ajouter de la documentation au fichier de code.

1. Ouvrez la vue Conversation en mode Question.

2. Ajoutez un contexte à l’invite de conversation. Par exemple, ajoutez un fichier Markdown qui fournit des instructions de documentation.

3. Entrez une requête pour générer la documentation du code en ligne. Par exemple, Vous pouvez entrer la requête suivante :

   @workspace /doc Create inline code documentation for the ConsoleApp class.
   

4. Passez en revue la documentation de code intégré suggérée dans la vue de chat.

   

5. Une fois que vous êtes satisfait de la documentation proposée, vous pouvez appliquer la documentation suggérée dans le fichier de code correspondant.

   Placez le pointeur de la souris sur la documentation suggérée pour afficher les boutons Appliquer, Insérer et Copier . Le bouton Appliquer est utilisé pour appliquer la documentation suggérée au fichier de code.

   Vous pouvez utiliser le bouton Insérer pour insérer la suggestion dans l’éditeur à la position actuelle du curseur ou le bouton Copier pour copier la suggestion dans le Presse-papiers.

6. Après avoir appliqué la documentation suggérée à votre fichier de code, vous pouvez parcourir les mises à jour pour accepter, rejeter ou modifier des suggestions individuelles.

   

   Utilisez les flèches haut et bas dans la barre de menus inférieure pour parcourir les mises à jour suggérées.

   Lorsque vous parcourez les suggestions, vous pouvez conserver ou annuler des suggestions individuelles à l’aide du menu contextuel qui s’affiche lorsque vous pointez sur la suggestion.

   Vous pouvez également modifier manuellement les suggestions en fonction des besoins.

7. Pour accepter ou rejeter toutes les suggestions, sélectionnez le bouton Conserver ou Annuler dans la barre de menus inférieure.

   Vous pouvez continuer à mettre à jour la documentation si nécessaire dans l’éditeur de code.

Génération d’une documentation de code en ligne à l’aide de la vue Chat en mode Planifier.

La vue Chat en mode Planifier permet d’élaborer un plan détaillé destiné à produire une documentation de code en ligne pour l’ensemble de votre projet. Le mode Plan analyse votre codebase et produit un plan pas à pas qui peut être remis au mode agent pour l’exécution.

1. Ouvrez l’affichage Conversation en mode Plan.

2. Saisissez une requête décrivant les tâches de documentation en ligne que vous souhaitez accomplir.

   Par exemple, Vous pouvez entrer la requête suivante :

   Create a plan for adding inline code documentation to the ConsoleApp class. Document the class, its properties, and methods. Identify all files that need documentation updates.
   

3. Passez en revue le plan d’implémentation.

   Après quelques instants, l’agent Planifier présente un plan dans la vue Chat. Le plan fournit un résumé général et une répartition des étapes, y compris toutes les questions ouvertes à des fins de clarification.

4. Une fois le plan terminé, sélectionnez Démarrer l’implémentation pour remettre le plan en mode agent, ou sélectionnez Ouvrir dans l’Éditeur pour enregistrer le plan en tant que fichier Markdown pour une utilisation ultérieure.

   Lorsque vous sélectionnez Start Implementation, GitHub Copilot bascule vers le mode agent et commence à ajouter la documentation du code inline en fonction du plan approuvé.

5. Passez en revue les fichiers mis à jour dans l’éditeur. Parcourez les mises à jour pour accepter, rejeter ou modifier des suggestions individuelles.

6. Pour accepter ou rejeter toutes les suggestions, sélectionnez le bouton Conserver ou Annuler dans la barre de menus inférieure. Vous pouvez également sélectionner les boutons Conserver ou Annuler dans la vue Conversation pour accepter ou rejeter toutes les suggestions.

   Vous pouvez continuer à mettre à jour la documentation si nécessaire dans l’éditeur de code.

Générer la documentation de code en ligne en utilisant la vue Conversation dans le mode Assistant

L’affichage Conversation en mode Agent peut être utilisé pour générer la documentation du code inline pour un projet, un fichier de code, une classe ou une méthode. Vous pouvez consulter la documentation inline suggérée et demander des mises à jour si nécessaire avant de mettre à jour le fichier de code.

1. Ouvrez la vue Conversation en mode Agent.

2. Ajoutez un contexte à l’invite de conversation. Par exemple, utilisez le bouton Attacher le contexte (icône paperclip) pour ajouter des dossiers de code source à la conversation.

3. Entrez une requête définissant vos tâches de documentation.

   Par exemple, Vous pouvez entrer la requête suivante :

   Create inline code documentation for all C# class files in the specified context. Document the class, properties, and methods. Do not add documentation to JSON, markdown, or other file types. Do not document UnitTest project files in the Test folder. Ensure that the solution builds without errors after the documentation is added.
   

   Le mode Agent ne prend pas en charge le participant de discussion @workspace ni la commande slash /doc, vous devez donc fournir un prompt détaillé.

4. L’agent affiche les messages d’état dans l’affichage Conversation à mesure qu’il termine les tâches demandées.

   

   L’agent peut également demander plus de contexte ou demander de l’aide pour effectuer les tâches demandées. Par exemple, l’agent peut demander l’autorisation avant d’exécuter une commande dans le terminal.

5. Attendez que l’agent termine les tâches de documentation demandées, puis passez en revue les fichiers mis à jour de l’éditeur.

   

   Une fois le mode Agent terminé, il affiche un résumé des tâches qu’il a effectuées. Vous pouvez consulter les fichiers mis à jour dans l’éditeur.

6. Parcourez les mises à jour pour accepter, rejeter ou modifier des suggestions individuelles.

   Pour accepter ou rejeter toutes les suggestions, sélectionnez le bouton Conserver ou Annuler dans la barre de menus inférieure. Vous pouvez également sélectionner les boutons Conserver ou Annuler dans la vue Conversation pour accepter ou rejeter toutes les suggestions.

   Vous pouvez continuer à mettre à jour la documentation si nécessaire dans l’éditeur de code.

Générer la documentation de code en ligne en utilisant l’action intelligente « Générer des documents »

L’action générer des documents intelligents peut être utilisée pour générer la documentation du code inline pour les classes, méthodes ou blocs de code complexes. Il s’agit d’un moyen rapide de générer la documentation sans devoir écrire une requête. L’action Générer la documentation active est disponible dans le menu contextuel lorsque vous cliquez avec le bouton droit sur le code sélectionné dans l’éditeur.

L'action Générer des Docs suggère de la documentation de code en ligne directement dans l'éditeur de code.

1. Ouvrez le fichier de code dans l’éditeur.

2. Sélectionnez le code que vous souhaitez documenter.

3. Cliquez avec le bouton droit sur le code sélectionné, sélectionnez Copilot, puis sélectionnez l’action intelligente Generate Docs active.

   

4. Passez en revue la documentation de code inline suggérée dans l’éditeur.

   

5. Utilisez le bouton Accepter accepter la mise à jour suggérée ou Fermer pour rejeter la mise à jour.

   Vous pouvez également utiliser le bouton Réexécuter l’invite avec ou sans mises à jour.

Générer la documentation de code en ligne à l’aide de la conversation en ligne

La fonctionnalité de conversation inline peut être utilisée pour générer la documentation du code inline pour les classes, méthodes ou blocs de code complexes. L’invite est utilisée pour spécifier le contexte ou pour fournir des instructions spécifiques. Vous pouvez également utiliser la commande slash /doc sans prompt textuel si vous le souhaitez.

La conversation en ligne propose de documenter le code en ligne directement dans l’éditeur de code.

1. Ouvrez le fichier de code dans l’éditeur.

2. Sélectionnez le code que vous souhaitez documenter.

3. Démarrez une session de conversation inline.

   Utilisez le raccourci clavier Ctrl+I ou sélectionnez la conversation inline de l’éditeur dans le menu Conversation .

4. Entrez une requête pour générer la documentation du code en ligne.

   Par exemple, vous pouvez documenter une méthode et demander des détails spécifiques :

   Document the selected method. List currentState options
   

5. Passez en revue la documentation de code inline suggérée dans l’éditeur.

   

6. Utilisez le bouton Accepter accepter la mise à jour suggérée ou Fermer pour rejeter la mise à jour.

   Vous pouvez également utiliser le bouton Réexécuter l’invite avec ou sans mises à jour.

Résumé

GitHub Copilot vous aide à générer rapidement et avec précision la documentation du code inline. La vue Conversation, la conversation inline et les fonctionnalités d’action intelligente fournissent différents niveaux d’interaction directement dans l’environnement Visual Studio Code.