From 27ef05325282d6037300a87900d26bfca9212863 Mon Sep 17 00:00:00 2001
From: Soreepeong <soreepeong@gmail.com>
Date: Sun, 25 Aug 2024 22:23:58 +0900
Subject: [PATCH] Update docs

---
 Dalamud/Utility/TaskExtensions.cs | 42 ++++++++++++++++++++-----------
 1 file changed, 28 insertions(+), 14 deletions(-)

diff --git a/Dalamud/Utility/TaskExtensions.cs b/Dalamud/Utility/TaskExtensions.cs
index 2855511a1..f03a9e9e9 100644
--- a/Dalamud/Utility/TaskExtensions.cs
+++ b/Dalamud/Utility/TaskExtensions.cs
@@ -63,20 +63,34 @@ public static class TaskExtensions
 #pragma warning restore RS0030
     }
 
-    /// <summary>Ignores any exceptions thrown from the task.</summary>
-    /// <param name="task">Task to ignore exceptions.</param>
-    /// <returns>A task that completes when <paramref name="task"/> completes in any state.</returns>
-    public static async Task SuppressException(this Task task)
-    {
-        try
-        {
-            await task;
-        }
-        catch
-        {
-            // ignore
-        }
-    }
+    /// <summary>Creates a new <see cref="Task"/> that resolves when <paramref name="task"/> completes, ignoring
+    /// exceptions thrown from the task, if any.</summary>
+    /// <param name="task">Task to await and ignore exceptions on failure.</param>
+    /// <returns>A <see cref="Task"/> that completes successfully when <paramref name="task"/> completes in any state.
+    /// </returns>
+    /// <remarks>Awaiting the returned <see cref="Task"/> will always complete without exceptions, but awaiting
+    /// <paramref name="task"/> will throw exceptions if it fails, even after this function is called.</remarks>
+    /// <example>
+    /// <para>
+    /// <b>Wrong use of this function</b>
+    /// <code>
+    /// var task = TaskThrowingException();
+    /// task.SuppressException();
+    /// await TaskThrowingException(); // This line will throw.
+    /// </code>
+    /// </para>
+    /// <para>
+    /// <b>Correct use of this function, if waiting for the task</b>
+    /// <code>await TaskThrowingException().SuppressException();</code>
+    /// </para>
+    /// <para>
+    /// <b>Fire-and-forget</b><br />
+    /// If not interested in the execution state of Task (fire-and-forget), simply calling this function will do.
+    /// This function consumes the task's exception, so that it won't bubble up on later garbage collection.
+    /// <code>TaskThrowingException().SuppressException();</code>
+    /// </para>
+    /// </example>
+    public static Task SuppressException(this Task task) => task.ContinueWith(static r => r.Exception);
 
     private static bool IsWaitingValid(Task task)
     {