Add remarks about stored exceptions (#8751)

Author: gewarren

xml/Microsoft.Extensions.Caching.Distributed/DistributedCacheExtensions.xml

@@ -89,7 +89,7 @@
         <param name="key">The key to get the stored data for.</param>
         <summary>Asynchronously gets a string from the specified cache with the specified key.</summary>
         <returns>A task that gets the string value from the stored cache key.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as <see cref="T:System.ArgumentException" />, are still thrown synchronously. For the stored exceptions, see the exceptions thrown by <see cref="M:Microsoft.Extensions.Caching.Distributed.DistributedCacheExtensions.GetString(Microsoft.Extensions.Caching.Distributed.IDistributedCache,System.String)" />.</remarks>
       </Docs>
     </Member>
     <Member MemberName="GetStringAsync">
@@ -131,7 +131,7 @@
         <param name="token">Optional. A <see cref="T:System.Threading.CancellationToken" /> to cancel the operation.</param>
         <summary>Asynchronously gets a string from the specified cache with the specified key.</summary>
         <returns>A task that gets the string value from the stored cache key.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as <see cref="T:System.ArgumentException" />, are still thrown synchronously. For the stored exceptions, see the exceptions thrown by <see cref="M:Microsoft.Extensions.Caching.Distributed.DistributedCacheExtensions.GetString(Microsoft.Extensions.Caching.Distributed.IDistributedCache,System.String)" />.</remarks>
       </Docs>
     </Member>
     <Member MemberName="Set">
@@ -200,7 +200,7 @@
         <param name="value">The data to store in the cache.</param>
         <summary>Asynchronously sets a sequence of bytes in the specified cache with the specified key.</summary>
         <returns>A task that represents the asynchronous set operation.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as <see cref="T:System.ArgumentException" />, are still thrown synchronously. For the stored exceptions, see the exceptions thrown by <see cref="M:Microsoft.Extensions.Caching.Distributed.DistributedCacheExtensions.Set(Microsoft.Extensions.Caching.Distributed.IDistributedCache,System.String,System.Byte[])" />.</remarks>
         <exception cref="T:System.ArgumentNullException">
           <paramref name="key" /> or <paramref name="value" /> is null.</exception>
       </Docs>
@@ -239,7 +239,7 @@
         <param name="token">Optional. A <see cref="T:System.Threading.CancellationToken" /> to cancel the operation.</param>
         <summary>Asynchronously sets a sequence of bytes in the specified cache with the specified key.</summary>
         <returns>A task that represents the asynchronous set operation.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as <see cref="T:System.ArgumentException" />, are still thrown synchronously. For the stored exceptions, see the exceptions thrown by <see cref="M:Microsoft.Extensions.Caching.Distributed.DistributedCacheExtensions.Set(Microsoft.Extensions.Caching.Distributed.IDistributedCache,System.String,System.Byte[])" />.</remarks>
         <exception cref="T:System.ArgumentNullException">
           <paramref name="key" /> or <paramref name="value" /> is null.</exception>
       </Docs>
@@ -351,7 +351,7 @@
         <param name="value">The data to store in the cache.</param>
         <summary>Asynchronously sets a string in the specified cache with the specified key.</summary>
         <returns>A task that represents the asynchronous set operation.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as <see cref="T:System.ArgumentException" />, are still thrown synchronously. For the stored exceptions, see the exceptions thrown by <see cref="M:Microsoft.Extensions.Caching.Distributed.DistributedCacheExtensions.SetString(Microsoft.Extensions.Caching.Distributed.IDistributedCache,System.String,System.String)" />.</remarks>
         <exception cref="T:System.ArgumentNullException">
           <paramref name="key" /> or <paramref name="value" /> is null.</exception>
       </Docs>
@@ -385,7 +385,7 @@
         <param name="options">The cache options for the entry.</param>
         <summary>Asynchronously sets a string in the specified cache with the specified key.</summary>
         <returns>A task that represents the asynchronous set operation.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as <see cref="T:System.ArgumentException" />, are still thrown synchronously. For the stored exceptions, see the exceptions thrown by <see cref="M:Microsoft.Extensions.Caching.Distributed.DistributedCacheExtensions.SetString(Microsoft.Extensions.Caching.Distributed.IDistributedCache,System.String,System.String,Microsoft.Extensions.Caching.Distributed.DistributedCacheEntryOptions)" />.</remarks>
         <exception cref="T:System.ArgumentNullException">
           <paramref name="key" /> or <paramref name="value" /> is null.</exception>
       </Docs>
@@ -424,7 +424,7 @@
         <param name="token">Optional. A <see cref="T:System.Threading.CancellationToken" /> to cancel the operation.</param>
         <summary>Asynchronously sets a string in the specified cache with the specified key.</summary>
         <returns>A task that represents the asynchronous set operation.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as <see cref="T:System.ArgumentException" />, are still thrown synchronously. For the stored exceptions, see the exceptions thrown by <see cref="M:Microsoft.Extensions.Caching.Distributed.DistributedCacheExtensions.SetString(Microsoft.Extensions.Caching.Distributed.IDistributedCache,System.String,System.String)" />.</remarks>
         <exception cref="T:System.ArgumentNullException">
           <paramref name="key" /> or <paramref name="value" /> is null.</exception>
       </Docs>
@@ -465,7 +465,7 @@
         <param name="token">Optional. A <see cref="T:System.Threading.CancellationToken" /> to cancel the operation.</param>
         <summary>Asynchronously sets a string in the specified cache with the specified key.</summary>
         <returns>A task that represents the asynchronous set operation.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as <see cref="T:System.ArgumentException" />, are still thrown synchronously. For the stored exceptions, see the exceptions thrown by <see cref="M:Microsoft.Extensions.Caching.Distributed.DistributedCacheExtensions.SetString(Microsoft.Extensions.Caching.Distributed.IDistributedCache,System.String,System.String,Microsoft.Extensions.Caching.Distributed.DistributedCacheEntryOptions)" />.</remarks>
         <exception cref="T:System.ArgumentNullException">
           <paramref name="key" /> or <paramref name="value" /> is null.</exception>
       </Docs>

xml/Microsoft.Extensions.Caching.Distributed/IDistributedCache.xml

@@ -82,7 +82,7 @@
         <param name="key">To be added.</param>
         <summary>To be added.</summary>
         <returns>To be added.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as <see cref="T:System.ArgumentException" />, are still thrown synchronously. For the stored exceptions, see the exceptions thrown by <see cref="M:Microsoft.Extensions.Caching.Distributed.IDistributedCache.Get(System.String)" />.</remarks>
       </Docs>
     </Member>
     <Member MemberName="GetAsync">
@@ -116,7 +116,7 @@
         <param name="token">Optional. The <see cref="T:System.Threading.CancellationToken" /> used to propagate notifications that the operation should be canceled.</param>
         <summary>Gets a value with the given key.</summary>
         <returns>The <see cref="T:System.Threading.Tasks.Task" /> that represents the asynchronous operation, containing the located value or null.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as <see cref="T:System.ArgumentException" />, are still thrown synchronously. For the stored exceptions, see the exceptions thrown by <see cref="M:Microsoft.Extensions.Caching.Distributed.IDistributedCache.Get(System.String)" />.</remarks>
       </Docs>
     </Member>
     <Member MemberName="Refresh">
@@ -175,7 +175,7 @@
         <param name="key">To be added.</param>
         <summary>To be added.</summary>
         <returns>To be added.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as <see cref="T:System.ArgumentException" />, are still thrown synchronously. For the stored exceptions, see the exceptions thrown by <see cref="M:Microsoft.Extensions.Caching.Distributed.IDistributedCache.Refresh(System.String)" />.</remarks>
       </Docs>
     </Member>
     <Member MemberName="RefreshAsync">
@@ -208,7 +208,7 @@
         <param name="token">Optional. The <see cref="T:System.Threading.CancellationToken" /> used to propagate notifications that the operation should be canceled.</param>
         <summary>Refreshes a value in the cache based on its key, resetting its sliding expiration timeout (if any).</summary>
         <returns>The <see cref="T:System.Threading.Tasks.Task" /> that represents the asynchronous operation.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as <see cref="T:System.ArgumentException" />, are still thrown synchronously. For the stored exceptions, see the exceptions thrown by <see cref="M:Microsoft.Extensions.Caching.Distributed.IDistributedCache.Refresh(System.String)" />.</remarks>
       </Docs>
     </Member>
     <Member MemberName="Remove">
@@ -267,7 +267,7 @@
         <param name="key">To be added.</param>
         <summary>To be added.</summary>
         <returns>To be added.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as <see cref="T:System.ArgumentException" />, are still thrown synchronously. For the stored exceptions, see the exceptions thrown by <see cref="M:Microsoft.Extensions.Caching.Distributed.IDistributedCache.Remove(System.String)" />.</remarks>
       </Docs>
     </Member>
     <Member MemberName="RemoveAsync">
@@ -300,7 +300,7 @@
         <param name="token">Optional. The <see cref="T:System.Threading.CancellationToken" /> used to propagate notifications that the operation should be canceled.</param>
         <summary>Removes the value with the given key.</summary>
         <returns>The <see cref="T:System.Threading.Tasks.Task" /> that represents the asynchronous operation.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as <see cref="T:System.ArgumentException" />, are still thrown synchronously. For the stored exceptions, see the exceptions thrown by <see cref="M:Microsoft.Extensions.Caching.Distributed.IDistributedCache.Remove(System.String)" />.</remarks>
       </Docs>
     </Member>
     <Member MemberName="Set">
@@ -367,7 +367,7 @@
         <param name="options">To be added.</param>
         <summary>To be added.</summary>
         <returns>To be added.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as <see cref="T:System.ArgumentException" />, are still thrown synchronously. For the stored exceptions, see the exceptions thrown by <see cref="M:Microsoft.Extensions.Caching.Distributed.IDistributedCache.Set(System.String,System.Byte[],Microsoft.Extensions.Caching.Distributed.DistributedCacheEntryOptions)" />.</remarks>
       </Docs>
     </Member>
     <Member MemberName="SetAsync">
@@ -404,7 +404,7 @@
         <param name="token">Optional. The <see cref="T:System.Threading.CancellationToken" /> used to propagate notifications that the operation should be canceled.</param>
         <summary>Sets the value with the given key.</summary>
         <returns>The <see cref="T:System.Threading.Tasks.Task" /> that represents the asynchronous operation.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>This method stores in the task it returns all non-usage exceptions that the method's synchronous counterpart can throw. If an exception is stored into the returned task, that exception will be thrown when the task is awaited. Usage exceptions, such as <see cref="T:System.ArgumentException" />, are still thrown synchronously. For the stored exceptions, see the exceptions thrown by <see cref="M:Microsoft.Extensions.Caching.Distributed.IDistributedCache.Set(System.String,System.Byte[],Microsoft.Extensions.Caching.Distributed.DistributedCacheEntryOptions)" />.</remarks>
       </Docs>
     </Member>
   </Members>