Demo: Generate inline code documentation by using GitHub Copilot Chat

Instructions

The demo activities are designed for an environment that includes the following resources:

• Visual Studio Code.
• The C# Dev Kit extension for Visual Studio Code.
• The GitHub Copilot and GitHub Copilot Chat extensions for Visual Studio Code. A GitHub account with an active subscription for GitHub Copilot is required.
• Sample code projects created using C#.

NOTE: We recommend that instructors consider using their own GitHub account and GitHub Copilot subscription for the demos. This will enable you to control and customize your dev environment. It will also make it easier to adjust the demos to fit the needs of your classrooms.

IMPORTANT: If you choose to run the demos in the hosted lab environment rather than your instructor PC, you can unzip the sample apps in the hosted environment. You will need to configure the GitHub Copilot extensions in the hosted environment before you can run the demos. You may find that the hosted environment is slower than your local environment, so you may need to adjust the pace of the demos accordingly.

Introduce the demo

Documenting your code is an important aspect of the software development process. Inline documentation (code comments) help developers understand the codebase, its purpose, and how to use it.

GitHub Copilot Chat can help you document your code quickly and accurately. You have a few options for generating inline documentation using GitHub Copilot Chat:

• Construct your own natural language prompt that can be used to generate specific documentation.
• Use the /doc command during an inline chat session to generate comments for selected code.
• Use the Generate Docs smart action to generate comments for selected code.

Properly documenting your code creates a more readable and maintainable codebase that’s easier for other developers to understand and work with.

Generate inline code documentation using the Chat view

In this demonstration, you use GitHub Copilot Chat to generate inline code documentation for the APL2007M2Sample1 project.

Use the following steps to complete this section of the demo:

1. Ensure that you have the APL2007M2Sample1 project open in Visual Studio Code.

2. Open the MainWindow.xaml.cs file.

3. Select all of the code starting from the namespace declaration to the end of the file.

4. Open the Chat view.

5. To see how GitHub Copilot Chat would document the selected code, enter the following prompt:

    @workspace #selection generate inline code documentation for the selected code
   

6. Take a minute to review the suggested code documentation.

   The generated response should look similar to the following code sample:

   
    namespace ParallelAsyncExample
    {
        public partial class MainWindow : Window
        {
            // HttpClient instance with a maximum response content buffer size of 1,000,000 bytes
            private readonly HttpClient _client = new HttpClient { MaxResponseContentBufferSize = 1_000_000 };
            // List of URLs to download content from
            private readonly IEnumerable<string> _urlList = new string[]
            {
                "https://docs.microsoft.com",
                "https://docs.microsoft.com/azure",
                "https://docs.microsoft.com/powershell",
                "https://docs.microsoft.com/dotnet",
                "https://docs.microsoft.com/aspnet/core",
                "https://docs.microsoft.com/windows",
                "https://docs.microsoft.com/office",
                "https://docs.microsoft.com/enterprise-mobility-security",
                "https://docs.microsoft.com/visualstudio",
                "https://docs.microsoft.com/microsoft-365",
                "https://docs.microsoft.com/sql",
                "https://docs.microsoft.com/dynamics365",
                "https://docs.microsoft.com/surface",
                "https://docs.microsoft.com/xamarin",
                "https://docs.microsoft.com/azure/devops",
                "https://docs.microsoft.com/system-center",
                "https://docs.microsoft.com/graph",
                "https://docs.microsoft.com/education",
                "https://docs.microsoft.com/gaming"
            };
            // Event handler for the start button click event
            private void OnStartButtonClick(object sender, RoutedEventArgs e)
            {
                // Disable the start button and clear the results text box
                _startButton.IsEnabled = false;
                _resultsTextBox.Clear();
                // Start the asynchronous operation to sum page sizes
                Task.Run(() => StartSumPageSizesAsync());
            }
            // Starts the asynchronous operation to sum page sizes
            private async Task StartSumPageSizesAsync()
            {
                // Perform the main download operation
                await SumPageSizesAsync();
                // Update the UI to re-enable the start button and indicate that control has returned
                await Dispatcher.BeginInvoke(() =>
                {
                    _resultsTextBox.Text += $"\nControl returned to {nameof(OnStartButtonClick)}.";
                    _startButton.IsEnabled = true;
                });
            }
            // Asynchronously sums the sizes of the pages from the URLs
            private async Task SumPageSizesAsync()
            {
                // Start a stopwatch to measure elapsed time
                var stopwatch = Stopwatch.StartNew();
                // Create tasks to download content from each URL
                IEnumerable<Task<int>> downloadTasksQuery =
                    from url in _urlList
                    select ProcessUrlAsync(url, _client);
                // Convert the sequence of tasks into an array
                Task<int>[] downloadTasks = downloadTasksQuery.ToArray();
                // Wait for all tasks to complete and sum the lengths of the downloaded content
                int[] lengths = await Task.WhenAll(downloadTasks);
                int total = lengths.Sum();
                // Update the UI with the total bytes and elapsed time
                await Dispatcher.BeginInvoke(() =>
                {
                    stopwatch.Stop();
                    _resultsTextBox.Text += $"\nTotal bytes returned:  {total:#,#}";
                    _resultsTextBox.Text += $"\nElapsed time:          {stopwatch.Elapsed}\n";
                });
            }
            // Asynchronously processes a URL by downloading its content and returning the length of the content
            private async Task<int> ProcessUrlAsync(string url, HttpClient client)
            {
                try
                {
                    // Download the content of the URL
                    byte[] byteArray = await client.GetByteArrayAsync(url);
                    // Update the UI with the URL and content length
                    await DisplayResultsAsync(url, byteArray);
                    // Return the length of the downloaded content
                    return byteArray.Length;
                }
                catch (HttpRequestException e)
                {
                    // Handle HTTP request exceptions by updating the UI with an error message
                    await Dispatcher.BeginInvoke(() =>
                    {
                        _resultsTextBox.Text += $"{url,-60} {"Error",-10}\n";
                        _resultsTextBox.Text += $"Exception: {e.Message}\n";
                    });
                    // Return 0 to indicate failure
                    return 0;
                }
            }
            // Updates the UI with the URL and the length of the downloaded content
            private Task DisplayResultsAsync(string url, byte[] content) =>
                Dispatcher.BeginInvoke(() =>
                    _resultsTextBox.Text += $"{url,-60} {content.Length,10:#,#}\n")
                          .Task;
            // Disposes of the HttpClient instance when the window is closed to free up resources
            protected override void OnClosed(EventArgs e) => _client.Dispose();
        }
    }
   
   

   The response includes suggested code comments and a portion of the associated code. Some of your code may be omitted for brevity. You could manually move code comments into the actual code file.

   Inline chat provides a more direct approach for adding comments to your code.

Generate inline code documentation using inline chat

1. Scroll to the top of the MainWindow.xaml.cs file.

2. Select the OnStartButtonClick method.

3. To open an inline chat, press Ctrl+I.

4. To generate inline documentation for the OnStartButtonClick method, enter the following prompt:

    /doc
   

5. Take a minute to review the code documentation generated.

   Notice that the suggested documentation for the OnStartButtonClick method includes a summary and descriptions of the two parameters. When a method includes a return value, a description of the return value is also included.

   [!IMPORTANT] Always review the GitHub Copilot’s suggested updates before accepting. If you discover an issue in a suggested code update, you can either discard the update or attempt to correct the issue before accepting the suggested code update.

6. To discard the suggested update, select Discard.

   In the next section, you generate documentation for all of the methods at once.

Generate inline code documentation using the Generate Docs smart action

The Generate Docs smart action is another way to generate inline code documentation. You can use this smart action to generate comments that describe the selected code.

Use the following steps to complete this section of the demo:

1. In the Visual Studio Code editor, select all of the methods inside the MainWindow class.

2. Right-click the selected code, select Copilot, and then select Generate Docs.

   Wait for the documentation to be generated.

3. Review the suggested changes.

   [!IMPORTANT] If you find issues in the generated documentation, modify the suggested changes before continuing.

4. Select Accept.

   Each of the methods in the MainWindow class now includes generated comments.

Summary

In this demo, you used GitHub Copilot Chat to generate inline code documentation for the APL2007M2Sample1 app. You learned how to generate inline code documentation using the Chat view, inline chat, and the Generate Docs smart action. By generating code comments, you can create a more readable and maintainable codebase that’s easier for other developers to understand and work with. Inline code documentation is an essential part of software development that helps developers understand the codebase, its purpose, and how to use it.