Создание встроенной документации по коду с помощью GitHub Copilot
Правильное документирование кода создает более удобочитаемую и поддерживаемую базу кода, которая проще для других разработчиков для понимания и работы с ней.
GitHub Copilot Чат может помочь вам быстро, точно и согласованно документируйте код.
Для создания встроенной документации по коду можно использовать каждую из следующих GitHub Copilot функций:
- Представление чата: используйте представление чата в режиме "Запрос", "Агент" или "План".
- Встроенный чат: используйте встроенный сеанс чата, чтобы документировать определенный код (классы, методы или блоки кода) без выхода из редактора.
- Интеллектуальные действия: выполните интеллектуальное действие "Создать документы", чтобы объяснить выбранный код, даже не записывая запрос.
Создание встроенной документации по коду с помощью представления чата
Представление чата можно использовать для создания встроенной документации по коду для проекта, файла кода, класса или метода. Перед обновлением файла кода можно просмотреть рекомендуемую документацию и запросить обновления.
Каждый из трех режимов представления чата (Ask, Agent и Plan) можно использовать для создания встроенной документации по коду. Стоимость использования режима агента выше, чем в других режимах, которые могут быть рассмотрены.
Создание встроенной документации по коду с помощью представления чата в режиме ask
Режим Ask можно использовать для оценки вашего кода и предложения встроенной документации кода для проектов, классов или методов. Рекомендуемую встроенную документацию можно просмотреть и создать обновления по мере необходимости перед добавлением документации в файл кода.
Откройте представление чата в режиме "Запрос".
Добавьте контекст в запрос чата. Например, добавьте файл markdown, предоставляющий рекомендации по документации.
Введите запрос для генерации встроенной документации кода. Например, можно ввести следующий запрос:
@workspace /doc Create inline code documentation for the ConsoleApp class.Ознакомьтесь с предлагаемой встроенной документацией по коду в представлении чата.
Как только вы будете удовлетворены предлагаемой документацией, ее можно будет применить к соответствующему файлу кода.
Наведите указатель мыши на предлагаемую документацию, чтобы просмотреть кнопки "Применить", " Вставка" и " Копировать ". Кнопка "Применить " используется для применения предлагаемой документации к файлу кода.
С помощью кнопки "Вставка" можно вставить предложение в редактор в текущей позиции курсора или кнопку "Копировать ", чтобы скопировать предложение в буфер обмена.
После применения предлагаемой документации к файлу кода можно перейти по обновлениям, чтобы принять, отклонить или изменить отдельные предложения.
Используйте стрелки вверх и вниз в нижней строке меню, чтобы перейти по предлагаемым обновлениям.
При переходе по предложениям можно сохранить или отменить отдельные предложения с помощью всплывающего меню, которое отображается при наведении указателя мыши на предложение.
Вы также можете вручную изменить предложения по мере необходимости.
Чтобы принять или отклонить все предложения, нажмите кнопку "Сохранить " или " Отменить " в нижней строке меню.
Вы можете продолжить обновление документации по мере необходимости в редакторе кода.
Создание встроенной документации по коду с помощью представления чата в режиме плана
Представление чата в режиме плана можно использовать для создания подробного плана для создания встроенной документации по коду в проекте. Режим плана анализирует базу кода и создает пошаговый план, который можно передать в режим агента для выполнения.
Откройте представление чата в режиме плана.
Введите запрос, описывающий встроенные задачи документации.
Например, можно ввести следующий запрос:
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.Просмотрите план реализации.
Через несколько минут агент плана выводит план в представлении чата. План содержит общее резюме и разбивку шагов, включая открытые вопросы для уточнения.
После завершения плана выберите "Запустить реализацию" , чтобы передать план в режим агента или нажмите кнопку "Открыть в редакторе ", чтобы сохранить план в виде файла Markdown для последующего использования.
При выборе Start Implementation GitHub Copilot переключается в режим агента и начинает добавлять встроенную документацию по коду на основе утвержденного плана.
Просмотрите обновленные файлы в редакторе. Перейдите по обновлениям, чтобы принять, отклонить или изменить отдельные предложения.
Чтобы принять или отклонить все предложения, нажмите кнопку "Сохранить " или " Отменить " в нижней строке меню. Вы также можете выбрать кнопки "Сохранить " или "Отменить " в представлении чата, чтобы принять или отклонить все предложения.
Вы можете продолжить обновление документации по мере необходимости в редакторе кода.
Создайте встроенную документацию кода, используя чат в агентском режиме
Представление чата в режиме агента можно использовать для создания встроенной документации по коду для проекта, файла кода, класса или метода. Перед обновлением файла кода можно просмотреть рекомендуемую встроенную документацию и запросить обновления.
Откройте представление чата в режиме агента.
Добавьте контекст в запрос чата. Например, нажмите кнопку "Подключить контекст " (значок с документом) для добавления папок исходного кода в чат.
Введите запрос, определяющий задачи документации.
Например, можно ввести следующий запрос:
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.Режим агента не поддерживает участника чата
@workspaceили команду слэш/doc, поэтому необходимо предоставить подробный запрос.Агент отображает сообщения о состоянии в представлении чата по мере выполнения запрошенных задач.
Агент также может запрашивать дополнительные контексты или запрашивать помощь для выполнения запрошенных задач. Например, агент может запросить разрешение перед выполнением команды в терминале.
Подождите, пока агент завершит запрошенные задачи документации, а затем просмотрите обновленные файлы редактора.
После завершения режима агента отображается сводка завершенных задач. Обновленные файлы можно просмотреть в редакторе.
Перейдите по обновлениям, чтобы принять, отклонить или изменить отдельные предложения.
Чтобы принять или отклонить все предложения, нажмите кнопку "Сохранить " или " Отменить " в нижней строке меню. Вы также можете выбрать кнопки "Сохранить " или "Отменить " в представлении чата, чтобы принять или отклонить все предложения.
Вы можете продолжить обновление документации по мере необходимости в редакторе кода.
Создание встроенной документации по коду с помощью интеллектуального действия "Создание документов"
Смарт-действие "Создать документы" можно использовать для создания встроенной документации по коду для классов, методов или сложных блоков кода. Это быстрый способ создания документации без необходимости писать запрос. Смарт-действие "Создать документы" доступно в контекстном меню при щелчке правой кнопкой мыши выбранный код в редакторе.
Смарт-действие "Генерация документации" предлагает документацию, встроенную в код, прямо в редакторе кода.
Откройте файл кода в редакторе.
Выберите код, который требуется документировать.
Щелкните правой кнопкой мыши выбранный код, выберите Copilot и выберите Generate Docs smart action.
Ознакомьтесь с предлагаемой встроенной кодовой документацией в редакторе.
Нажмите кнопку "Принять" принять предлагаемое обновление или закрыть , чтобы отклонить обновление.
Можно также использовать кнопку повторного запуска , чтобы повторно запустить запрос с обновлениями или без нее.
Создание встроенной документации по коду с помощью встроенного чата
Функцию встроенного чата можно использовать для создания встроенной документации по коду для классов, методов или сложных блоков кода. Запрос используется для указания контекста или предоставления конкретных инструкций. Вы также можете использовать команду /doc с косой чертой без текстового запроса, если хотите.
Встроенный чат предлагает документацию по встроенному коду непосредственно в редакторе кода.
Откройте файл кода в редакторе.
Выберите код, который требуется документировать.
Запустите встроенный сеанс чата.
Используйте сочетание клавиш CTRL+I или выберите встроенный чат редактора в меню чата .
Введите запрос для генерации встроенной документации кода.
Например, можно задокументируйте метод и запросить конкретные сведения:
Document the selected method. List currentState optionsОзнакомьтесь с предлагаемой встроенной кодовой документацией в редакторе.
Нажмите кнопку "Принять" принять предлагаемое обновление или закрыть , чтобы отклонить обновление.
Можно также использовать кнопку повторного запуска , чтобы повторно запустить запрос с обновлениями или без нее.
Сводка
GitHub Copilot помогает быстро и точно создавать встроенную документацию по коду. Представление чата, встроенный чат и функции смарт-действий предоставляют различные уровни взаимодействия непосредственно в среде Visual Studio Code.