Gerar documentação de código embutido usando GitHub Copilot

Concluído

Documentar corretamente seu código cria uma base de código mais legível e de fácil manutenção, que é mais fácil de ser compreendida e trabalhada por outros desenvolvedores

GitHub Copilot Chat pode ajudá-lo a documentar o código de forma rápida, precisa e consistente.

Cada um dos seguintes recursos de GitHub Copilot pode ser usado para criar a documentação de código embutido:

• Modo de exibição de Chat: use a exibição de Chat no modo Perguntar, Agente ou Plano.
• Chat embutido: use uma sessão de chat embutida para documentar código específico (classes, métodos ou blocos de código) sem sair do editor.
• Ações inteligentes: execute a ação inteligente Gerar Documentos para explicar o código selecionado sem precisar escrever um prompt.

Gerar documentação de código embutido usando o modo de exibição chat

A Janela de Chat pode ser usada para gerar documentação de código inline para um projeto, arquivo de código, classe ou método. Você pode examinar a documentação sugerida e solicitar atualizações conforme necessário antes de atualizar o arquivo de código.

Cada um dos três modos da visualização do Chat (Perguntar, Agente e Plano) pode ser usado para gerar documentação embutida de código. O custo de usar o modo agent é maior do que os outros modos, o que pode ser uma consideração.

Gerar documentação de código inline usando a vista de chat na opção Perguntar

O modo Ask pode ser usado para avaliar seu código e sugerir documentação de código embutido para projetos, classes ou métodos. Você pode examinar a documentação embutida sugerida e gerar atualizações conforme necessário antes de adicionar a documentação ao arquivo de código.

1. Abra o modo de exibição de chat no modo Perguntar.

2. Adicione contexto ao prompt de chat. Por exemplo, adicione um arquivo markdown que fornece diretrizes de documentação.

3. Insira um prompt para gerar a documentação de código em linha. Por exemplo, você pode inserir o seguinte prompt:

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

4. Revise a documentação de código em linha sugerida na visualização de Chat.

   

5. Quando estiver satisfeito com a documentação proposta, você poderá aplicar a documentação sugerida ao arquivo de código correspondente.

   Passe o ponteiro do mouse sobre a documentação sugerida para ver os botões Aplicar, Inserir e Copiar . O botão Aplicar é usado para aplicar a documentação sugerida ao arquivo de código.

   Você pode usar o botão Inserir para inserir a sugestão no editor na posição atual do cursor ou no botão Copiar para copiar a sugestão para a área de transferência.

6. Depois de aplicar a documentação sugerida ao arquivo de código, você pode navegar pelas atualizações para aceitar, rejeitar ou modificar sugestões individuais.

   

   Use as setas para cima e para baixo na barra de menus inferior para navegar pelas atualizações sugeridas.

   Ao navegar pelas sugestões, você pode manter ou desfazer sugestões individuais usando o menu pop-up que aparece quando você passa o mouse sobre a sugestão.

   Você também pode modificar manualmente as sugestões conforme necessário.

7. Para aceitar ou rejeitar todas as sugestões, selecione o botão Manter ou Desfazer na barra de menus inferior.

   Você pode continuar atualizando a documentação conforme necessário no editor de código.

Gerar documentação de código em linha usando a "Visualização de chat" no "Modo de plano"

A visualização de Chat no modo Planejamento pode ser usada para criar um plano detalhado para gerar documentação de código embutido em seu projeto. O modo Plano analisa sua base de código e produz um plano passo a passo que pode ser entregue ao modo de agente para execução.

1. Abra a visualização de chat no modo de plano.

2. Insira um prompt que descreva suas tarefas de documentação interna.

   Por exemplo, você pode inserir o seguinte prompt:

   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. Examine o plano de implementação.

   Após alguns instantes, o agente do Plano gera um plano na visualização de chat. O plano fornece um resumo de alto nível e um detalhamento das etapas, incluindo quaisquer perguntas abertas para esclarecimentos.

4. Depois que o plano for concluído, selecione Iniciar Implementação para entregar o plano ao modo de agente ou selecione Abrir no Editor para salvar o plano como um arquivo Markdown para uso posterior.

   Quando você seleciona Start Implementation, GitHub Copilot alterna para o modo de agente e começa a adicionar a documentação de código embutido com base no plano aprovado.

5. Examine os arquivos atualizados no editor. Navegue pelas atualizações para aceitar, rejeitar ou modificar sugestões individuais.

6. Para aceitar ou rejeitar todas as sugestões, selecione o botão Manter ou Desfazer na barra de menus inferior. Você também pode selecionar os botões Manter ou Desfazer no modo de exibição chat para aceitar ou rejeitar todas as sugestões.

   Você pode continuar atualizando a documentação conforme necessário no editor de código.

Gerar a documentação de código em linha usando o modo de exibição de chat no modo Agente

A visualização de chat no modo Agente pode ser usada para gerar documentação de código em linha para um projeto, arquivo de código, classe ou método. Você pode examinar a documentação embutida sugerida e solicitar atualizações conforme necessário antes de atualizar o arquivo de código.

1. Abra a exibição de Chat no modo Agente.

2. Adicione contexto ao prompt de chat. Por exemplo, use o botão Anexar Contexto (ícone paperclip) para adicionar pastas de código-fonte ao chat.

3. Insira um prompt que define suas tarefas de documentação.

   Por exemplo, você pode inserir o seguinte prompt:

   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.
   

   O modo Agente não dá suporte ao participante @workspace ou ao comando barra /doc, portanto, você precisa fornecer um prompt detalhado.

4. O agente exibe mensagens de status no modo de exibição chat à medida que conclui as tarefas solicitadas.

   

   O agente também pode solicitar mais contexto ou solicitar assistência para concluir as tarefas solicitadas. Por exemplo, o agente pode pedir permissão antes de executar um comando no terminal.

5. Aguarde até que o agente conclua as tarefas de documentação solicitadas e examine os arquivos atualizados do editor.

   

   Quando o modo Agent for concluído, ele exibirá um resumo das tarefas que concluiu. Você pode examinar os arquivos atualizados no editor.

6. Navegue pelas atualizações para aceitar, rejeitar ou modificar sugestões individuais.

   Para aceitar ou rejeitar todas as sugestões, selecione o botão Manter ou Desfazer na barra de menus inferior. Você também pode selecionar os botões Manter ou Desfazer no modo de exibição chat para aceitar ou rejeitar todas as sugestões.

   Você pode continuar atualizando a documentação conforme necessário no editor de código.

Gerar documentação de código embutido usando a ação inteligente "Gerar Documentos"

A ação inteligente Gerar Documentos pode ser usada para gerar documentação de código embutido para classes, métodos ou blocos de código complexos. É uma maneira rápida de gerar documentação sem a necessidade de gravar um prompt. A ação inteligente Gerar Documentos está disponível no menu de contexto quando você clica com o botão direito do mouse no código selecionado no editor.

A ação inteligente Gerar Documentos sugere a documentação de código embutido diretamente no editor de código.

1. Abra o arquivo de código no editor.

2. Selecione o código que você deseja documentar.

3. Clique com o botão direito do mouse no código selecionado, selecione Copilot e selecione a ação inteligente Generate Docs.

   

4. Revise a documentação de código em linha sugerida no editor.

   

5. Use o botão Aceitar para aceitar a atualização sugerida ou Fechar para rejeitar a atualização.

   Você também pode usar o botão Executar Novamente para executar novamente o prompt com ou sem atualizações.

Gerar documentação de código embutido usando chat embutido

O recurso de chat embutido pode ser usado para gerar documentação de código embutido para classes, métodos ou blocos de código complexos. O prompt é usado para especificar o contexto ou para fornecer instruções específicas. Você também pode usar o comando de barra /doc sem um prompt de texto, se desejar.

O chat embutido sugere a documentação de código em linha diretamente no editor de código.

1. Abra o arquivo de código no editor.

2. Selecione o código que você deseja documentar.

3. Inicie uma sessão de chat embutida.

   Use o atalho de teclado Ctrl+I ou selecione o Chat Embutido do Editor no menu Chat .

4. Insira um prompt para gerar a documentação de código em linha.

   Por exemplo, você pode documentar um método e solicitar detalhes específicos:

   Document the selected method. List currentState options
   

5. Revise a documentação de código em linha sugerida no editor.

   

6. Use o botão Aceitar para aceitar a atualização sugerida ou Fechar para rejeitar a atualização.

   Você também pode usar o botão Executar Novamente para executar novamente o prompt com ou sem atualizações.

Resumo

GitHub Copilot ajuda você a gerar a documentação de código embutido de forma rápida e precisa. O modo de exibição de chat, o chat embutido e os recursos de ação inteligente fornecem vários níveis de interação diretamente dentro do ambiente Visual Studio Code.