From d2282d5c3e34055c9d8416bcf3a7c0f940436ffe Mon Sep 17 00:00:00 2001
From: Edward Brey <edward@breyfamily.net>
Date: Wed, 24 Apr 2019 00:39:29 -0500
Subject: [PATCH] Document affect of a suspended system on delay

[This poor guy](https://stackoverflow.com/q/38207026/145173) has to reverse engineer `Task.Delay` to figure out what would happen if the system were suspended after it was called. This change documents the behavior.

Someone should verify that the behavior is uniform for all platforms, and if not, document the variations.
---
 xml/System.Threading.Tasks/Task.xml | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/xml/System.Threading.Tasks/Task.xml b/xml/System.Threading.Tasks/Task.xml
index 5b75130d0b2..24f273a315f 100644
--- a/xml/System.Threading.Tasks/Task.xml
+++ b/xml/System.Threading.Tasks/Task.xml
@@ -2106,7 +2106,7 @@ End Sub
         <Parameter Name="millisecondsDelay" Type="System.Int32" Index="0" FrameworkAlternate="dotnet-uwp-10.0;netcore-1.0;netcore-1.1;netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8;netstandard-1.0;netstandard-1.1;netstandard-1.2;netstandard-1.3;netstandard-1.4;netstandard-1.6;netstandard-2.0;netstandard-2.1;xamarinandroid-7.1;xamarinios-10.8;xamarinmac-3.0" />
       </Parameters>
       <Docs>
-        <param name="millisecondsDelay">The number of milliseconds to wait before completing the returned task, or -1 to wait indefinitely.</param>
+        <param name="millisecondsDelay">The number of milliseconds to wait before completing the returned task, or -1 to wait indefinitely. This time does not include any time that passes while the system is suspended (e.g. in Standby or Hibernate).</param>
         <summary>Creates a task that completes after a specified number of milliseconds.</summary>
         <returns>A task that represents the time delay.</returns>
         <remarks>
@@ -2177,7 +2177,7 @@ End Sub
         <Parameter Name="delay" Type="System.TimeSpan" Index="0" FrameworkAlternate="dotnet-uwp-10.0;netcore-1.0;netcore-1.1;netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8;netstandard-1.0;netstandard-1.1;netstandard-1.2;netstandard-1.3;netstandard-1.4;netstandard-1.6;netstandard-2.0;netstandard-2.1;xamarinandroid-7.1;xamarinios-10.8;xamarinmac-3.0" />
       </Parameters>
       <Docs>
-        <param name="delay">The time span to wait before completing the returned task, or <see langword="TimeSpan.FromMilliseconds(-1)" /> to wait indefinitely.</param>
+        <param name="delay">The time span to wait before completing the returned task, or <see langword="TimeSpan.FromMilliseconds(-1)" /> to wait indefinitely. This time does not include any time that passes while the system is suspended (e.g. in Standby or Hibernate).</param>
         <summary>Creates a task that completes after a specified time interval.</summary>
         <returns>A task that represents the time delay.</returns>
         <remarks>
@@ -2243,7 +2243,7 @@ End Sub
         <Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="1" FrameworkAlternate="dotnet-uwp-10.0;netcore-1.0;netcore-1.1;netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8;netstandard-1.0;netstandard-1.1;netstandard-1.2;netstandard-1.3;netstandard-1.4;netstandard-1.6;netstandard-2.0;netstandard-2.1;xamarinandroid-7.1;xamarinios-10.8;xamarinmac-3.0" />
       </Parameters>
       <Docs>
-        <param name="millisecondsDelay">The number of milliseconds to wait before completing the returned task, or -1 to wait indefinitely.</param>
+        <param name="millisecondsDelay">The number of milliseconds to wait before completing the returned task, or -1 to wait indefinitely. This time does not include any time that passes while the system is suspended (e.g. in Standby or Hibernate).</param>
         <param name="cancellationToken">A cancellation token to observe while waiting for the task to complete.</param>
         <summary>Creates a cancellable task that completes after a specified number of milliseconds.</summary>
         <returns>A task that represents the time delay.</returns>
@@ -2307,7 +2307,7 @@ End Sub
         <Parameter Name="cancellationToken" Type="System.Threading.CancellationToken" Index="1" FrameworkAlternate="dotnet-uwp-10.0;netcore-1.0;netcore-1.1;netcore-2.0;netcore-2.1;netcore-2.2;netcore-3.0;netframework-4.5;netframework-4.5.1;netframework-4.5.2;netframework-4.6;netframework-4.6.1;netframework-4.6.2;netframework-4.7;netframework-4.7.1;netframework-4.7.2;netframework-4.8;netstandard-1.0;netstandard-1.1;netstandard-1.2;netstandard-1.3;netstandard-1.4;netstandard-1.6;netstandard-2.0;netstandard-2.1;xamarinandroid-7.1;xamarinios-10.8;xamarinmac-3.0" />
       </Parameters>
       <Docs>
-        <param name="delay">The time span to wait before completing the returned task, or <see langword="TimeSpan.FromMilliseconds(-1)" /> to wait indefinitely.</param>
+        <param name="delay">The time span to wait before completing the returned task, or <see langword="TimeSpan.FromMilliseconds(-1)" /> to wait indefinitely. This time does not include any time that passes while the system is suspended (e.g. in Standby or Hibernate).</param>
         <param name="cancellationToken">A cancellation token to observe while waiting for the task to complete.</param>
         <summary>Creates a cancellable task that completes after a specified time interval.</summary>
         <returns>A task that represents the time delay.</returns>