Allow articles with missing shortTitles to appear on home page (#54389)

content/copilot/copilot-chat-cookbook/documenting-code/explaining-complex-algorithms-or-logic.md

@@ -0,0 +1,171 @@
+---
+title: 'Explaining complex algorithms or logic'
+shortTitle: Explain complex logic
+intro: '{% data variables.product.prodname_copilot_chat_short %} can help add clear and concise documentation on complex algorithms or logic.'
+redirect_from:
+  - /copilot/example-prompts-for-github-copilot-chat/documenting-code/explaining-complex-algorithms-or-logic
+versions:
+  feature: copilot
+category:
+  - 'Documenting code'
+complexity:
+  - Intermediate
+octicon: book
+topics:
+  - Copilot
+---
+
+There may be times where you need to explain complex algorithms or logic in your code. This can be challenging, especially when you're trying to make it understandable to others. {% data variables.product.prodname_copilot_chat_short %} can help you with this task by providing you with suggestions on how to explain the algorithm or logic in a clear and concise manner.
+
+## Example scenario
+
+In the C# code below, we have a method which fetches data, retries if there's an error, and updates a status label. You might want to explain, in comments in the code, how the method works and how it handles retries and cancellations.
+
+```csharp
+private static readonly HttpClient _client = new HttpClient();
+
+public async Task<string> FetchDataFromApiWithRetryAsync(string apiUrl, CancellationToken cancellationToken, int maxRetries, int cancellationDelay, Label statusLabel)
+{
+    var retryCount = 0;
+    using var cts = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
+
+    while (retryCount < maxRetries)
+    {
+        try
+        {
+            cts.CancelAfter(cancellationDelay);
+            return await FetchDataFromApiAsync(cts.Token, statusLabel);
+        }
+        catch (Exception ex) when (!(ex is OperationCanceledException))
+        {
+            if (retryCount < maxRetries - 1) {
+                retryCount++;
+                int delay = (int)Math.Pow(2, retryCount) * 1000;
+                await Task.Delay(delay, cancellationToken);
+                UpdateStatusLabel($"Retrying ({retryCount}/{maxRetries})...", statusLabel);
+            } else {
+                throw new Exception($"Failed to fetch data after {maxRetries} retries: {ex.Message}", ex);
+            }
+        }
+    }
+
+    throw new OperationCanceledException("The operation was cancelled.", cts.Token);
+}
+
+private async Task<string> FetchDataFromApiAsync(string apiUrl, CancellationToken cancellationToken, Label statusLabel)
+{
+    UpdateStatusLabel("Fetching data...", statusLabel);
+
+    HttpResponseMessage response = await _client.GetAsync(apiUrl, cancellationToken);
+    response.EnsureSuccessStatusCode();
+    string data = await response.Content.ReadAsStringAsync();
+
+    UpdateStatusLabel("Data fetched.", statusLabel);
+    return data;
+}
+
+private void UpdateStatusLabel(string message, Label statusLabel)
+{
+    if (statusLabel.InvokeRequired) {
+        statusLabel.BeginInvoke(new Action<string, Label>(UpdateStatusLabel), message, statusLabel);
+    } else {
+        statusLabel.Text = message;
+    }
+}
+```
+
+## Example prompt
+
+We can ask {% data variables.product.prodname_copilot_chat_short %} to make this code easier to understand using comments.
+
+`Add comments to this code to make it more understandable`
+
+## Example response
+
+{% data reusables.copilot.example-prompts.response-is-an-example %}
+
+{% data variables.product.prodname_copilot_short %} responds with an overview of the update it suggests, and the code snippet with the comments added:
+
+```csharp
+// Shared HttpClient instance for making HTTP requests (best practice for reuse)
+private static readonly HttpClient _client = new HttpClient();
+
+/// <summary>
+/// Fetches data from an API with retry mechanism and timeout functionality
+/// </summary>
+/// <param name="apiUrl">The URL to fetch data from</param>
+/// <param name="cancellationToken">Token to cancel the operation</param>
+/// <param name="maxRetries">Maximum number of retry attempts</param>
+/// <param name="cancellationDelay">Timeout duration in milliseconds</param>
+/// <param name="statusLabel">UI label to show status updates</param>
+public async Task<string> FetchDataFromApiWithRetryAsync(string apiUrl, CancellationToken cancellationToken, int maxRetries, int cancellationDelay, Label statusLabel)
+{
+    var retryCount = 0;
+    // Create a linked cancellation token that combines user cancellation and timeout
+    using var cts = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
+
+    while (retryCount < maxRetries)
+    {
+        try
+        {
+            // Set timeout for this attempt
+            cts.CancelAfter(cancellationDelay);
+            return await FetchDataFromApiAsync(cts.Token, statusLabel);
+        }
+        catch (Exception ex) when (!(ex is OperationCanceledException))
+        {
+            // If not the last retry attempt, implement exponential backoff
+            if (retryCount < maxRetries - 1) {
+                retryCount++;
+                // Exponential backoff: 2^retryCount seconds (1s, 2s, 4s, 8s, etc.)
+                int delay = (int)Math.Pow(2, retryCount) * 1000;
+                await Task.Delay(delay, cancellationToken);
+                UpdateStatusLabel($"Retrying ({retryCount}/{maxRetries})...", statusLabel);
+            } else {
+                // If all retries failed, throw exception with details
+                throw new Exception($"Failed to fetch data after {maxRetries} retries: {ex.Message}", ex);
+            }
+        }
+    }
+
+    // This is reached if maxRetries is 0 or some other unexpected case
+    throw new OperationCanceledException("The operation was cancelled.", cts.Token);
+}
+
+/// <summary>
+/// Makes the actual API call to fetch data
+/// </summary>
+private async Task<string> FetchDataFromApiAsync(string apiUrl, CancellationToken cancellationToken, Label statusLabel)
+{
+    UpdateStatusLabel("Fetching data...", statusLabel);
+
+    // Perform HTTP GET request with cancellation support
+    HttpResponseMessage response = await _client.GetAsync(apiUrl, cancellationToken);
+    response.EnsureSuccessStatusCode(); // Throws if response is not successful
+    string data = await response.Content.ReadAsStringAsync();
+
+    UpdateStatusLabel("Data fetched.", statusLabel);
+    return data;
+}
+
+/// <summary>
+/// Updates UI label text safely across threads
+/// </summary>
+/// <param name="message">The message to display</param>
+/// <param name="statusLabel">The label control to update</param>
+private void UpdateStatusLabel(string message, Label statusLabel)
+{
+    // Check if we need to invoke on UI thread
+    if (statusLabel.InvokeRequired) {
+        // Use BeginInvoke to update label on UI thread
+        statusLabel.BeginInvoke(new Action<string, Label>(UpdateStatusLabel), message, statusLabel);
+    } else {
+        // Direct update if already on UI thread
+        statusLabel.Text = message;
+    }
+}
+```
+
+## Further reading
+
+{% data reusables.copilot.example-prompts.further-reading-items %}