Port Microsoft.Extensions new docs (#10208)

* Microsoft.Extensions.Caching.Distributed
* Microsoft.Extensions.Caching.Hybrid
* Microsoft.Extensions.Caching.Memory
* Microsoft.Extensions.Configuration
* Microsoft.Extensions.DependencyInjection
* Microsoft.Extensions.FileProviders.Physical
* Microsoft.Extensions.Hosting
* Microsoft.Extensions.Hosting.WindowsServices
* Microsoft.Extensions.Http.Logging
* Microsoft.Extensions.Logging
* Microsoft.Extensions.Logging.Abstractions
* Microsoft.Extensions.Logging.Configuration
* Microsoft.Extensions.Logging.Console
* Microsoft.Extensions.Logging.EventSource
---------
Co-authored-by: David Cantú <dacantu@microsoft.com>

Author: carlossanlop

xml/Microsoft.Extensions.Caching.Distributed/IBufferDistributedCache.xml

@@ -21,7 +21,7 @@
     </Attribute>
   </Attributes>
   <Docs>
-    <summary>To be added.</summary>
+    <summary>Represents a distributed cache of serialized values, with support for low allocation data transfer.</summary>
     <remarks>To be added.</remarks>
   </Docs>
   <Members>
@@ -53,11 +53,11 @@
         <Parameter Name="options" Type="Microsoft.Extensions.Caching.Distributed.DistributedCacheEntryOptions" />
       </Parameters>
       <Docs>
-        <param name="key">To be added.</param>
-        <param name="value">To be added.</param>
-        <param name="options">To be added.</param>
-        <summary>To be added.</summary>
-        <remarks>To be added.</remarks>
+        <param name="key">The key of the entry to create.</param>
+        <param name="value">The value for this cache entry.</param>
+        <param name="options">The cache options for the entry.</param>
+        <summary>Sets or overwrites a cache item.</summary>
+        <remarks>This is functionally similar to <see cref="M:Microsoft.Extensions.Caching.Distributed.IDistributedCache.Set(System.String,System.Byte[],Microsoft.Extensions.Caching.Distributed.DistributedCacheEntryOptions)" />, but avoids the array allocation.</remarks>
       </Docs>
     </Member>
     <Member MemberName="SetAsync">
@@ -88,13 +88,13 @@
         <Parameter Name="token" Type="System.Threading.CancellationToken" />
       </Parameters>
       <Docs>
-        <param name="key">To be added.</param>
-        <param name="value">To be added.</param>
-        <param name="options">To be added.</param>
-        <param name="token">To be added.</param>
-        <summary>To be added.</summary>
+        <param name="key">The key of the entry to create.</param>
+        <param name="value">The value for this cache entry.</param>
+        <param name="options">The cache options for the value.</param>
+        <param name="token">The <see cref="T:System.Threading.CancellationToken" /> used to propagate notifications that the operation should be canceled.</param>
+        <summary>Asynchronously sets or overwrites a cache entry.</summary>
         <returns>To be added.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>This is functionally similar to <see cref="M:Microsoft.Extensions.Caching.Distributed.IDistributedCache.SetAsync(System.String,System.Byte[],Microsoft.Extensions.Caching.Distributed.DistributedCacheEntryOptions,System.Threading.CancellationToken)" />, but avoids the array allocation.</remarks>
       </Docs>
     </Member>
     <Member MemberName="TryGet">
@@ -117,11 +117,12 @@
         <Parameter Name="destination" Type="System.Buffers.IBufferWriter&lt;System.Byte&gt;" />
       </Parameters>
       <Docs>
-        <param name="key">To be added.</param>
-        <param name="destination">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
-        <remarks>To be added.</remarks>
+        <param name="key">The unique key for the cache item.</param>
+        <param name="destination">The target to write the cache contents on success.</param>
+        <summary>Attempts to retrieve an existing cache item.</summary>
+        <returns>
+          <see langword="true" /> if the cache item is found, <see langword="false" /> otherwise.</returns>
+        <remarks>This is functionally similar to <see cref="M:Microsoft.Extensions.Caching.Distributed.IDistributedCache.Get(System.String)" />, but avoids the array allocation.</remarks>
       </Docs>
     </Member>
     <Member MemberName="TryGetAsync">
@@ -150,12 +151,13 @@
         <Parameter Name="token" Type="System.Threading.CancellationToken" />
       </Parameters>
       <Docs>
-        <param name="key">To be added.</param>
-        <param name="destination">To be added.</param>
-        <param name="token">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
-        <remarks>To be added.</remarks>
+        <param name="key">The unique key for the cache entry.</param>
+        <param name="destination">The target to write the cache contents on success.</param>
+        <param name="token">The <see cref="T:System.Threading.CancellationToken" /> used to propagate notifications that the operation should be canceled.</param>
+        <summary>Asynchronously attempts to retrieve an existing cache entry.</summary>
+        <returns>
+          <see langword="true" /> if the cache entry is found, <see langword="false" /> otherwise.</returns>
+        <remarks>This is functionally similar to <see cref="M:Microsoft.Extensions.Caching.Distributed.IDistributedCache.GetAsync(System.String,System.Threading.CancellationToken)" />, but avoids the array allocation.</remarks>
       </Docs>
     </Member>
   </Members>

xml/Microsoft.Extensions.Caching.Hybrid/HybridCache.xml

@@ -24,7 +24,7 @@
     </Attribute>
   </Attributes>
   <Docs>
-    <summary>To be added.</summary>
+    <summary>Provides multi-tier caching services building on <see cref="T:Microsoft.Extensions.Caching.Distributed.IDistributedCache" /> backends.</summary>
     <remarks>To be added.</remarks>
   </Docs>
   <Members>
@@ -215,9 +215,9 @@
       <Docs>
         <param name="keys">To be added.</param>
         <param name="token">To be added.</param>
-        <summary>To be added.</summary>
+        <summary>Asynchronously removes the value associated with the key if it exists.</summary>
         <returns>To be added.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>Implementors should treat <see langword="null" /> as empty.</remarks>
       </Docs>
     </Member>
     <Member MemberName="RemoveAsync">
@@ -241,7 +241,7 @@
       <Docs>
         <param name="key">To be added.</param>
         <param name="token">To be added.</param>
-        <summary>To be added.</summary>
+        <summary>Asynchronously removes the value associated with the key if it exists.</summary>
         <returns>To be added.</returns>
         <remarks>To be added.</remarks>
       </Docs>
@@ -267,9 +267,9 @@
       <Docs>
         <param name="tags">To be added.</param>
         <param name="token">To be added.</param>
-        <summary>To be added.</summary>
+        <summary>Asynchronously removes all values associated with the specified tags.</summary>
         <returns>To be added.</returns>
-        <remarks>To be added.</remarks>
+        <remarks>Implementors should treat <see langword="null" /> as empty.</remarks>
       </Docs>
     </Member>
     <Member MemberName="RemoveByTagAsync">
@@ -293,7 +293,7 @@
       <Docs>
         <param name="tag">To be added.</param>
         <param name="token">To be added.</param>
-        <summary>To be added.</summary>
+        <summary>Asynchronously removes all values associated with the specified tag.</summary>
         <returns>To be added.</returns>
         <remarks>To be added.</remarks>
       </Docs>

xml/Microsoft.Extensions.Caching.Hybrid/HybridCacheEntryFlags.xml

@@ -19,7 +19,7 @@
     </Attribute>
   </Attributes>
   <Docs>
-    <summary>To be added.</summary>
+    <summary>Specifies additional flags that apply to a <see cref="T:Microsoft.Extensions.Caching.Hybrid.HybridCache" /> operation.</summary>
     <remarks>To be added.</remarks>
   </Docs>
   <Members>
@@ -40,7 +40,7 @@
       </ReturnValue>
       <MemberValue>32</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Disables compression for this payload.</summary>
       </Docs>
     </Member>
     <Member MemberName="DisableDistributedCache">
@@ -60,7 +60,7 @@
       </ReturnValue>
       <MemberValue>12</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Disables both reading from and writing to the secondary distributed cache.</summary>
       </Docs>
     </Member>
     <Member MemberName="DisableDistributedCacheRead">
@@ -80,7 +80,7 @@
       </ReturnValue>
       <MemberValue>4</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Disables reading from the secondary distributed cache.</summary>
       </Docs>
     </Member>
     <Member MemberName="DisableDistributedCacheWrite">
@@ -100,7 +100,7 @@
       </ReturnValue>
       <MemberValue>8</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Disables writing to the secondary distributed cache.</summary>
       </Docs>
     </Member>
     <Member MemberName="DisableLocalCache">
@@ -120,7 +120,7 @@
       </ReturnValue>
       <MemberValue>3</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Disables both reading from and writing to the local in-process cache.</summary>
       </Docs>
     </Member>
     <Member MemberName="DisableLocalCacheRead">
@@ -140,7 +140,7 @@
       </ReturnValue>
       <MemberValue>1</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Disables reading from the local in-process cache.</summary>
       </Docs>
     </Member>
     <Member MemberName="DisableLocalCacheWrite">
@@ -160,7 +160,7 @@
       </ReturnValue>
       <MemberValue>2</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Disables writing to the local in-process cache.</summary>
       </Docs>
     </Member>
     <Member MemberName="DisableUnderlyingData">
@@ -180,7 +180,7 @@
       </ReturnValue>
       <MemberValue>16</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Only fetches the value from cache; does not attempt to access the underlying data store.</summary>
       </Docs>
     </Member>
     <Member MemberName="None">
@@ -200,7 +200,7 @@
       </ReturnValue>
       <MemberValue>0</MemberValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>No additional flags.</summary>
       </Docs>
     </Member>
   </Members>

xml/Microsoft.Extensions.Caching.Hybrid/HybridCacheEntryOptions.xml

@@ -14,7 +14,12 @@
   </Base>
   <Interfaces />
   <Docs>
-    <summary>To be added.</summary>
+    <summary>
+      <para>Specifies dditional options, such as expiration, that apply to a <see cref="T:Microsoft.Extensions.Caching.Hybrid.HybridCache" /> operation. When options</para>
+      <para>can be specified at multiple levels (for example, globally and per-call), the values are composed; the</para>
+      <para>most granular non-<see langword="null" /> value is used, with <see langword="null" /> values being inherited. If no value is specified at</para>
+      <para>any level, the implementation can choose a reasonable default.</para>
+    </summary>
     <remarks>To be added.</remarks>
   </Docs>
   <Members>
@@ -51,7 +56,7 @@
         <ReturnType>System.Nullable&lt;System.TimeSpan&gt;</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Gets or sets the overall cache duration of this entry, passed to the backend distributed cache.</summary>
         <value>To be added.</value>
         <remarks>To be added.</remarks>
       </Docs>
@@ -72,7 +77,7 @@
         <ReturnType>System.Nullable&lt;Microsoft.Extensions.Caching.Hybrid.HybridCacheEntryFlags&gt;</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Gets or sets additional flags that apply to the requested operation.</summary>
         <value>To be added.</value>
         <remarks>To be added.</remarks>
       </Docs>
@@ -95,7 +100,10 @@
       <Docs>
         <summary>To be added.</summary>
         <value>To be added.</value>
-        <remarks>To be added.</remarks>
+        <remarks>
+          <para>When retrieving a cached value from an external cache store, this value will be used to calculate the local</para>
+          <para>cache expiration, not exceeding the remaining overall cache lifetime.</para>
+        </remarks>
       </Docs>
     </Member>
   </Members>

xml/Microsoft.Extensions.Caching.Hybrid/IHybridCacheSerializerFactory.xml

@@ -17,7 +17,7 @@
     </Attribute>
   </Attributes>
   <Docs>
-    <summary>To be added.</summary>
+    <summary>Factory provider for per-type <see cref="T:Microsoft.Extensions.Caching.Hybrid.IHybridCacheSerializer`1" /> instances.</summary>
     <remarks>To be added.</remarks>
   </Docs>
   <Members>
@@ -54,10 +54,11 @@
         </Parameter>
       </Parameters>
       <Docs>
-        <typeparam name="T">To be added.</typeparam>
-        <param name="serializer">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <typeparam name="T">The type being serialized/deserialized.</typeparam>
+        <param name="serializer">The serializer.</param>
+        <summary>Requests a serializer for the provided type, if possible.</summary>
+        <returns>
+          <see langword="true" /> if the factory supports this type, <see langword="false" /> otherwise.</returns>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>

xml/Microsoft.Extensions.Caching.Hybrid/IHybridCacheSerializer`1.xml

@@ -21,8 +21,8 @@
   </TypeParameters>
   <Interfaces />
   <Docs>
-    <typeparam name="T">To be added.</typeparam>
-    <summary>To be added.</summary>
+    <typeparam name="T">The type being serialized/deserialized.</typeparam>
+    <summary>Provides per-type serialization and deserialization support for <see cref="T:Microsoft.Extensions.Caching.Hybrid.HybridCache" />.</summary>
     <remarks>To be added.</remarks>
   </Docs>
   <Members>
@@ -52,7 +52,7 @@
       </Parameters>
       <Docs>
         <param name="source">To be added.</param>
-        <summary>To be added.</summary>
+        <summary>Deserializes a <typeparamref name="T" /> value from the provided <paramref name="source" />.</summary>
         <returns>To be added.</returns>
         <remarks>To be added.</remarks>
       </Docs>
@@ -85,7 +85,7 @@
       <Docs>
         <param name="value">To be added.</param>
         <param name="target">To be added.</param>
-        <summary>To be added.</summary>
+        <summary>Serializes <paramref name="value" /> to the provided <paramref name="target" />.</summary>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>

xml/Microsoft.Extensions.Caching.Memory/CacheExtensions.xml

@@ -192,13 +192,13 @@
         </Parameter>
       </Parameters>
       <Docs>
-        <typeparam name="TItem">To be added.</typeparam>
-        <param name="cache">To be added.</param>
-        <param name="key">To be added.</param>
-        <param name="factory">To be added.</param>
-        <param name="createOptions">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <typeparam name="TItem">The type of the object to get.</typeparam>
+        <param name="cache">The <see cref="T:Microsoft.Extensions.Caching.Memory.IMemoryCache" /> instance this method extends.</param>
+        <param name="key">The key of the entry to look for or create.</param>
+        <param name="factory">The factory that creates the value associated with this key if the key does not exist in the cache.</param>
+        <param name="createOptions">The options to be applied to the <see cref="T:Microsoft.Extensions.Caching.Memory.ICacheEntry" /> if the key does not exist in the cache.</param>
+        <summary>Gets the value associated with this key if it exists, or generates a new entry using the provided key and a value from the given factory if the key is not found.</summary>
+        <returns>The value associated with this key.</returns>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>
@@ -288,13 +288,13 @@
         </Parameter>
       </Parameters>
       <Docs>
-        <typeparam name="TItem">To be added.</typeparam>
-        <param name="cache">To be added.</param>
-        <param name="key">To be added.</param>
-        <param name="factory">To be added.</param>
-        <param name="createOptions">To be added.</param>
-        <summary>To be added.</summary>
-        <returns>To be added.</returns>
+        <typeparam name="TItem">The type of the object to get.</typeparam>
+        <param name="cache">The <see cref="T:Microsoft.Extensions.Caching.Memory.IMemoryCache" /> instance this method extends.</param>
+        <param name="key">The key of the entry to look for or create.</param>
+        <param name="factory">The factory task that creates the value associated with this key if the key does not exist in the cache.</param>
+        <param name="createOptions">The options to be applied to the <see cref="T:Microsoft.Extensions.Caching.Memory.ICacheEntry" /> if the key does not exist in the cache.</param>
+        <summary>Asynchronously gets the value associated with this key if it exists, or generates a new entry using the provided key and a value from the given factory if the key is not found.</summary>
+        <returns>The task object representing the asynchronous operation.</returns>
         <remarks>To be added.</remarks>
       </Docs>
     </Member>

xml/Microsoft.Extensions.Caching.Memory/MemoryCache.xml

@@ -42,7 +42,7 @@
     </Attribute>
   </Attributes>
   <Docs>
-    <summary>An implementation of <see cref="T:Microsoft.Extensions.Caching.Memory.IMemoryCache" /> using a dictionary to
+    <summary>Implements <see cref="T:Microsoft.Extensions.Caching.Memory.IMemoryCache" /> using a dictionary to
             store its entries.</summary>
     <remarks>To be added.</remarks>
   </Docs>
@@ -323,7 +323,7 @@
         <ReturnType>System.Collections.Generic.IEnumerable&lt;System.Object&gt;</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>To be added.</summary>
+        <summary>Gets an enumerable of the all the keys in the <see cref="T:Microsoft.Extensions.Caching.Memory.MemoryCache" />.</summary>
         <value>To be added.</value>
         <remarks>To be added.</remarks>
       </Docs>