Create docs transport package and turn on extensions source of truth (#…

…89312) * Create docs ref+xml transport package Contributes to #996. Add a nuget package that contains all the reference assemblies and source-of-truth API docs XML files for the current release. * Turn on source of truth for Microsoft.Extensions.* Make the source of truth for API docs for the Microsoft.Extensions.* libraries dotnet/runtime instead of the intellisense package. Disable the few projects that aren't yet documented. Same for libraries that are already effectively source-of-truth in runtime but which aren't documented. * Add missing triple slash docs in Primitives * Fill in missing keyed DI doc comments. * Add memory cache triple slash docs * Add more missing docs * Add more missing docs * More missing docs * More docs * More * Add Microsoft.Extensions.Logging.Console docs * Microsoft.Extensions.Hosting docs * Exclude Microsoft.Bcl.* * Update src/libraries/Microsoft.Internal.Runtime.DotNetApiDocs.Transport/src/Microsoft.Internal.Runtime.DotNetApiDocs.Transport.proj Co-authored-by: Carlos Sánchez López <[email protected]> --------- Co-authored-by: Tarek Mahmoud Sayed <[email protected]> Co-authored-by: Aditya Mandaleeka <[email protected]> Co-authored-by: Carlos Sánchez López <[email protected]>
dotnet · Jul 31, 2023 · 75ecb1a · 75ecb1a
1 parent fa9ad22
commit 75ecb1a
Show file tree

Hide file tree

Showing 46 changed files with 608 additions and 25 deletions.
diff --git a/eng/intellisense.targets b/eng/intellisense.targets
@@ -1,40 +1,46 @@
-<Project InitialTargets="VerifyAssemblySupportsDocsXmlGeneration">
+<Project>
 
   <PropertyGroup>
-    <UseIntellisensePackageDocXmlFile Condition="'$(UseIntellisensePackageDocXmlFile)' == ''">true</UseIntellisensePackageDocXmlFile>
+    <UseCompilerGeneratedDocXmlFile Condition="'$(UseCompilerGeneratedDocXmlFile)' == '' and $(MSBuildProjectName.StartsWith('Microsoft.Extensions.'))">true</UseCompilerGeneratedDocXmlFile>
   </PropertyGroup>
 
-  <Target Name="VerifyAssemblySupportsDocsXmlGeneration"
-          Condition="'$(UseIntellisensePackageDocXmlFile)' != 'true'">
-    <Error Text="The 'UseIntellisensePackageDocXmlFile' property is not supported for partial facade assemblies: $(AssemblyName)"
-           Condition="'$(IsPartialFacadeAssembly)' == 'true'" />
-    <Error Text="The 'UseIntellisensePackageDocXmlFile' property is not supported for assemblies that throw PlatformNotSupportedException: $(AssemblyName)"
-           Condition="'$(GeneratePlatformNotSupportedAssemblyMessage)' != ''" />
-  </Target>
-
-  <PropertyGroup Condition="'$(UseIntellisensePackageDocXmlFile)' == 'true'">
+  <PropertyGroup Condition="'$(UseCompilerGeneratedDocXmlFile)' != 'true'">
     <IntellisensePackageXmlRootFolder>$([MSBuild]::NormalizeDirectory('$(NuGetPackageRoot)', 'microsoft.private.intellisense', '$(MicrosoftPrivateIntellisenseVersion)', 'IntellisenseFiles'))</IntellisensePackageXmlRootFolder>
     <IntellisensePackageXmlFilePathFromNetFolder>$([MSBuild]::NormalizePath('$(IntellisensePackageXmlRootFolder)', 'net', '1033', '$(AssemblyName).xml'))</IntellisensePackageXmlFilePathFromNetFolder>
     <IntellisensePackageXmlFilePathFromDotNetPlatExtFolder>$([MSBuild]::NormalizePath('$(IntellisensePackageXmlRootFolder)', 'dotnet-plat-ext', '1033', '$(AssemblyName).xml'))</IntellisensePackageXmlFilePathFromDotNetPlatExtFolder>
     <IntellisensePackageXmlFilePath Condition="'$(IntellisensePackageXmlFilePath)' == '' and Exists($(IntellisensePackageXmlFilePathFromNetFolder))">$(IntellisensePackageXmlFilePathFromNetFolder)</IntellisensePackageXmlFilePath>
     <IntellisensePackageXmlFilePath Condition="'$(IntellisensePackageXmlFilePath)' == '' and Exists($(IntellisensePackageXmlFilePathFromDotNetPlatExtFolder))">$(IntellisensePackageXmlFilePathFromDotNetPlatExtFolder)</IntellisensePackageXmlFilePath>
+
+    <!-- If the intellisense package doesn't provide an XML, use the compiler generated one instead. -->
+    <UseCompilerGeneratedDocXmlFile Condition="'$(IntellisensePackageXmlFilePath)' == '' and '$(GenerateDocumentationFile)' == 'true'">true</UseCompilerGeneratedDocXmlFile>
+
     <!-- Suppress "CS1591 - Missing XML comment for publicly visible type or member" compiler errors if
          - the intellisense package xml file is used or
          - the assembly is private (i.e. System.Private.Uri) or
          - the assembly is a PNSE assembly. -->
-    <NoWarn Condition="'$(IntellisensePackageXmlFilePath)' != '' or
+    <NoWarn Condition="'$(UseCompilerGeneratedDocXmlFile)' != 'true' or
                        '$(IsPrivateAssembly)' == 'true' or
                        '$(GeneratePlatformNotSupportedAssemblyMessage)' != ''">$(NoWarn);1591</NoWarn>
   </PropertyGroup>
 
+  <!-- Flow these properties to consuming projects for Microsoft.Internal.Runtime.DotNetApiDocs.Transport.proj to only
+       include the source of truth compiler generated documentation files. -->
+  <ItemDefinitionGroup>
+    <TargetPathWithTargetPlatformMoniker>
+      <UseCompilerGeneratedDocXmlFile>$(UseCompilerGeneratedDocXmlFile)</UseCompilerGeneratedDocXmlFile>
+      <IsPartialFacadeAssembly>$(IsPartialFacadeAssembly)</IsPartialFacadeAssembly>
+      <IsPlatformNotSupportedAssembly Condition="'$(GeneratePlatformNotSupportedAssemblyMessage)' != ''">true</IsPlatformNotSupportedAssembly>
+    </TargetPathWithTargetPlatformMoniker>
+  </ItemDefinitionGroup>
+
   <ItemGroup>
     <PackageDownload Include="Microsoft.Private.Intellisense" Version="[$(MicrosoftPrivateIntellisenseVersion)]" />
   </ItemGroup>
 
   <!-- Replace the compiler generated xml file in the obj folder with the one that comes from the intellisense package. -->
   <Target Name="ChangeDocumentationFileForPackaging"
           BeforeTargets="CopyFilesToOutputDirectory;DocumentationProjectOutputGroup"
-          Condition="'$(IntellisensePackageXmlFilePath)' != ''">
+          Condition="'$(UseCompilerGeneratedDocXmlFile)' != 'true' and '$(IntellisensePackageXmlFilePath)' != ''">
     <ItemGroup>
       <DocFileItem Remove="@(DocFileItem)" />
       <DocFileItem Include="$(IntellisensePackageXmlFilePath)" />

diff --git a/src/libraries/Directory.Build.props b/src/libraries/Directory.Build.props
@@ -2,7 +2,7 @@
   <PropertyGroup>
     <DisableArcadeTestFramework>true</DisableArcadeTestFramework>
     <!-- Enabling this rule will cause build failures on undocumented public APIs.
-         We cannot add it in eng/Versions.props because src/coreclr does not have access to UseIntellisensePackageDocXmlFile, which ensures
+         We cannot add it in eng/Versions.props because src/coreclr does not have access to UseCompilerGeneratedDocXmlFile, which ensures
          we only enable it in specific projects. so to avoid duplicating this property in coreclr, we can first scope it to src/libraries.
          This property needs to be declared before the ..\..\Directory.Build.props import. -->
     <SkipArcadeNoWarnCS1591>true</SkipArcadeNoWarnCS1591>

diff --git a/src/libraries/Microsoft.Bcl.AsyncInterfaces/src/Microsoft.Bcl.AsyncInterfaces.csproj b/src/libraries/Microsoft.Bcl.AsyncInterfaces/src/Microsoft.Bcl.AsyncInterfaces.csproj
@@ -1,4 +1,5 @@
 <Project Sdk="Microsoft.NET.Sdk">
+
   <PropertyGroup>
     <TargetFrameworks>netstandard2.0;$(NetFrameworkMinimum);netstandard2.1</TargetFrameworks>
     <IsPackable>true</IsPackable>
@@ -9,10 +10,14 @@ Commonly Used Types:
 System.IAsyncDisposable
 System.Collections.Generic.IAsyncEnumerable
 System.Collections.Generic.IAsyncEnumerator</PackageDescription>
+    <!-- This library uses IsPartialFacadeAssembly for which the compiler doesn't produce any XML documentation. -->
+    <UseCompilerGeneratedDocXmlFile>false</UseCompilerGeneratedDocXmlFile>
   </PropertyGroup>
+
   <PropertyGroup>
     <IsPartialFacadeAssembly Condition="'$(TargetFramework)' == 'netstandard2.1'">true</IsPartialFacadeAssembly>
   </PropertyGroup>
+
   <ItemGroup Condition="'$(IsPartialFacadeAssembly)' != 'true'">
     <Compile Include="System\Threading\Tasks\Sources\ManualResetValueTaskSourceCore.cs" />
     <Compile Include="System\Runtime\CompilerServices\AsyncIteratorMethodBuilder.cs" />
@@ -40,8 +45,10 @@ System.Collections.Generic.IAsyncEnumerator</PackageDescription>
     <Compile Include="$(CoreLibSharedDir)\System\Runtime\CompilerServices\EnumeratorCancellationAttribute.cs">
       <Link>System.Private.CoreLib\System\Runtime\CompilerServices\EnumeratorCancellationAttribute.cs</Link>
     </Compile>
+
   </ItemGroup>
   <ItemGroup Condition="'$(IsPartialFacadeAssembly)' != 'true'">
     <PackageReference Include="System.Threading.Tasks.Extensions" Version="$(SystemThreadingTasksExtensionsVersion)" />
   </ItemGroup>
+
 </Project>
diff --git a/src/libraries/Microsoft.Bcl.Cryptography/src/Microsoft.Bcl.Cryptography.csproj b/src/libraries/Microsoft.Bcl.Cryptography/src/Microsoft.Bcl.Cryptography.csproj
@@ -1,4 +1,5 @@
 <Project Sdk="Microsoft.NET.Sdk">
+
   <PropertyGroup>
     <TargetFrameworks>$(NetCoreAppCurrent);netstandard2.0;$(NetFrameworkMinimum)</TargetFrameworks>
     <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
@@ -11,6 +12,8 @@
 
 Commonly Used Types:
 System.Security.Cryptography.SP800108HmacCounterKdf</PackageDescription>
+    <!-- This library uses IsPartialFacadeAssembly for which the compiler doesn't produce any XML documentation. -->
+    <UseCompilerGeneratedDocXmlFile>false</UseCompilerGeneratedDocXmlFile>
   </PropertyGroup>
 
   <PropertyGroup>
@@ -72,4 +75,5 @@ System.Security.Cryptography.SP800108HmacCounterKdf</PackageDescription>
   <ItemGroup Condition="'$(TargetFrameworkIdentifier)' != '.NETCoreApp'">
     <PackageReference Include="System.Memory" Version="$(SystemMemoryVersion)" />
   </ItemGroup>
+
 </Project>
diff --git a/src/libraries/Microsoft.Bcl.TimeProvider/src/Microsoft.Bcl.TimeProvider.csproj b/src/libraries/Microsoft.Bcl.TimeProvider/src/Microsoft.Bcl.TimeProvider.csproj
@@ -12,6 +12,8 @@
 Commonly Used Types:
 System.TimeProvider
 System.ITimer</PackageDescription>
+    <!-- This library uses IsPartialFacadeAssembly for which the compiler doesn't produce any XML documentation. -->
+    <UseCompilerGeneratedDocXmlFile>false</UseCompilerGeneratedDocXmlFile>
   </PropertyGroup>
 
   <PropertyGroup>

diff --git a/src/libraries/Microsoft.Extensions.Caching.Abstractions/src/CacheEntryExtensions.cs b/src/libraries/Microsoft.Extensions.Caching.Abstractions/src/CacheEntryExtensions.cs
@@ -7,6 +7,9 @@
 
 namespace Microsoft.Extensions.Caching.Memory
 {
+    /// <summary>
+    /// Provide extensions methods for <see cref="ICacheEntry"/> operations.
+    /// </summary>
     public static class CacheEntryExtensions
     {
         /// <summary>

diff --git a/src/libraries/Microsoft.Extensions.Caching.Abstractions/src/CacheItemPriority.cs b/src/libraries/Microsoft.Extensions.Caching.Abstractions/src/CacheItemPriority.cs
@@ -9,9 +9,24 @@ namespace Microsoft.Extensions.Caching.Memory
     /// </summary>
     public enum CacheItemPriority
     {
+        /// <summary>
+        /// The cache entry should be removed as soon as possible during memory pressure triggered cleanup.
+        /// </summary>
         Low,
+
+        /// <summary>
+        /// The cache entry should be removed if there is no other low priority cache entries during memory pressure triggered cleanup.
+        /// </summary>
         Normal,
+
+        /// <summary>
+        /// The cache entry should be removed only when there is no other low or normal priority cache entries during memory pressure triggered cleanup.
+        /// </summary>
         High,
+
+        /// <summary>
+        /// The cache entry should never be removed during memory pressure triggered cleanup.
+        /// </summary>
         NeverRemove,
     }
 }
diff --git a/...ibraries/Microsoft.Extensions.Caching.Abstractions/src/DistributedCacheEntryExtensions.cs b/...ibraries/Microsoft.Extensions.Caching.Abstractions/src/DistributedCacheEntryExtensions.cs
@@ -5,6 +5,9 @@
 
 namespace Microsoft.Extensions.Caching.Distributed
 {
+    /// <summary>
+    /// Extension methods for <see cref="DistributedCacheEntryOptions"/> operations.
+    /// </summary>
     public static class DistributedCacheEntryExtensions
     {
         /// <summary>

diff --git a/src/libraries/Microsoft.Extensions.Caching.Abstractions/src/EvictionReason.cs b/src/libraries/Microsoft.Extensions.Caching.Abstractions/src/EvictionReason.cs
@@ -3,32 +3,38 @@
 
 namespace Microsoft.Extensions.Caching.Memory
 {
+    /// <summary>
+    /// Specify the reasons why an entry was evicted from the cache.
+    /// </summary>
     public enum EvictionReason
     {
+        /// <summary>
+        /// The item was not removed from the cache.
+        /// </summary>
         None,
 
         /// <summary>
-        /// Manually
+        /// The item was removed from the cache manually.
         /// </summary>
         Removed,
 
         /// <summary>
-        /// Overwritten
+        /// The item was removed from the cache because it was overwritten.
         /// </summary>
         Replaced,
 
         /// <summary>
-        /// Timed out
+        /// The item was removed from the cache because it timed out.
         /// </summary>
         Expired,
 
         /// <summary>
-        /// Event
+        /// The item was removed from the cache because its token expired.
         /// </summary>
         TokenExpired,
 
         /// <summary>
-        /// Overflow
+        /// The item was removed from the cache because it exceeded its capacity.
         /// </summary>
         Capacity,
     }

diff --git a/src/libraries/Microsoft.Extensions.Caching.Abstractions/src/MemoryCacheEntryExtensions.cs b/src/libraries/Microsoft.Extensions.Caching.Abstractions/src/MemoryCacheEntryExtensions.cs
@@ -6,6 +6,9 @@
 
 namespace Microsoft.Extensions.Caching.Memory
 {
+    /// <summary>
+    /// Provide extensions methods for <see cref="MemoryCacheEntryOptions"/> operations.
+    /// </summary>
     public static class MemoryCacheEntryExtensions
     {
         /// <summary>

diff --git a/src/libraries/Microsoft.Extensions.Caching.Abstractions/src/MemoryCacheExtensions.cs b/src/libraries/Microsoft.Extensions.Caching.Abstractions/src/MemoryCacheExtensions.cs
@@ -7,19 +7,43 @@
 
 namespace Microsoft.Extensions.Caching.Memory
 {
+    /// <summary>
+    /// Provide extensions methods for <see cref="IMemoryCache"/> operations.
+    /// </summary>
     public static class CacheExtensions
     {
+        /// <summary>
+        /// Gets the value associated with this key if present.
+        /// </summary>
+        /// <param name="cache">The <see cref="IMemoryCache"/> instance this method extends.</param>
+        /// <param name="key">The key of the value to get.</param>
+        /// <returns>The value associated with this key, or <c>null</c> if the key is not present.</returns>
         public static object? Get(this IMemoryCache cache, object key)
         {
             cache.TryGetValue(key, out object? value);
             return value;
         }
 
+        /// <summary>
+        /// Gets the value associated with this key if present.
+        /// </summary>
+        /// <typeparam name="TItem">The type of the object to get.</typeparam>
+        /// <param name="cache">The <see cref="IMemoryCache"/> instance this method extends.</param>
+        /// <param name="key">The key of the value to get.</param>
+        /// <returns>The value associated with this key, or <c>default(TItem)</c> if the key is not present.</returns>
         public static TItem? Get<TItem>(this IMemoryCache cache, object key)
         {
             return (TItem?)(cache.Get(key) ?? default(TItem));
         }
 
+        /// <summary>
+        /// Try to get the value associated with the given key.
+        /// </summary>
+        /// <typeparam name="TItem">The type of the object to get.</typeparam>
+        /// <param name="cache">The <see cref="IMemoryCache"/> instance this method extends.</param>
+        /// <param name="key">The key of the value to get.</param>
+        /// <param name="value">The value associated with the given key.</param>
+        /// <returns><c>true</c> if the key was found. <c>false</c> otherwise.</returns>
         public static bool TryGetValue<TItem>(this IMemoryCache cache, object key, out TItem? value)
         {
             if (cache.TryGetValue(key, out object? result))
@@ -41,6 +65,14 @@ public static bool TryGetValue<TItem>(this IMemoryCache cache, object key, out T
             return false;
         }
 
+        /// <summary>
+        /// Associate a value with a key in the <see cref="IMemoryCache"/>.
+        /// </summary>
+        /// <typeparam name="TItem">The type of the object to set.</typeparam>
+        /// <param name="cache">The <see cref="IMemoryCache"/> instance this method extends.</param>
+        /// <param name="key">The key of the entry to add.</param>
+        /// <param name="value">The value to associate with the key.</param>
+        /// <returns>The value that was set.</returns>
         public static TItem Set<TItem>(this IMemoryCache cache, object key, TItem value)
         {
             using ICacheEntry entry = cache.CreateEntry(key);
@@ -49,6 +81,15 @@ public static TItem Set<TItem>(this IMemoryCache cache, object key, TItem value)
             return value;
         }
 
+        /// <summary>
+        /// Sets a cache entry with the given key and value that will expire in the given duration.
+        /// </summary>
+        /// <typeparam name="TItem">The type of the object to set.</typeparam>
+        /// <param name="cache">The <see cref="IMemoryCache"/> instance this method extends.</param>
+        /// <param name="key">The key of the entry to add.</param>
+        /// <param name="value">The value to associate with the key.</param>
+        /// <param name="absoluteExpiration">The point in time at which the cache entry will expire.</param>
+        /// <returns>The value that was set.</returns>
         public static TItem Set<TItem>(this IMemoryCache cache, object key, TItem value, DateTimeOffset absoluteExpiration)
         {
             using ICacheEntry entry = cache.CreateEntry(key);
@@ -58,6 +99,15 @@ public static TItem Set<TItem>(this IMemoryCache cache, object key, TItem value,
             return value;
         }
 
+        /// <summary>
+        /// Sets a cache entry with the given key and value that will expire in the given duration from now.
+        /// </summary>
+        /// <typeparam name="TItem">The type of the object to set.</typeparam>
+        /// <param name="cache">The <see cref="IMemoryCache"/> instance this method extends.</param>
+        /// <param name="key">The key of the entry to add.</param>
+        /// <param name="value">The value to associate with the key.</param>
+        /// <param name="absoluteExpirationRelativeToNow">The duration from now after which the cache entry will expire.</param>
+        /// <returns>The value that was set.</returns>
         public static TItem Set<TItem>(this IMemoryCache cache, object key, TItem value, TimeSpan absoluteExpirationRelativeToNow)
         {
             using ICacheEntry entry = cache.CreateEntry(key);
@@ -67,6 +117,15 @@ public static TItem Set<TItem>(this IMemoryCache cache, object key, TItem value,
             return value;
         }
 
+        /// <summary>
+        /// Sets a cache entry with the given key and value that will expire when <see cref="IChangeToken"/> expires.
+        /// </summary>
+        /// <typeparam name="TItem">The type of the object to set.</typeparam>
+        /// <param name="cache">The <see cref="IMemoryCache"/> instance this method extends.</param>
+        /// <param name="key">The key of the entry to add.</param>
+        /// <param name="value">The value to associate with the key.</param>
+        /// <param name="expirationToken">The <see cref="IChangeToken"/> that causes the cache entry to expire.</param>
+        /// <returns>The value that was set.</returns>
         public static TItem Set<TItem>(this IMemoryCache cache, object key, TItem value, IChangeToken expirationToken)
         {
             using ICacheEntry entry = cache.CreateEntry(key);
@@ -76,6 +135,15 @@ public static TItem Set<TItem>(this IMemoryCache cache, object key, TItem value,
             return value;
         }
 
+        /// <summary>
+        /// Sets a cache entry with the given key and value and apply the values of an existing <see cref="MemoryCacheEntryOptions"/> to the created entry.
+        /// </summary>
+        /// <typeparam name="TItem">The type of the object to set.</typeparam>
+        /// <param name="cache">The <see cref="IMemoryCache"/> instance this method extends.</param>
+        /// <param name="key">The key of the entry to add.</param>
+        /// <param name="value">The value to associate with the key.</param>
+        /// <param name="options">The existing <see cref="MemoryCacheEntryOptions"/> instance to apply to the new entry.</param>
+        /// <returns>The value that was set.</returns>
         public static TItem Set<TItem>(this IMemoryCache cache, object key, TItem value, MemoryCacheEntryOptions? options)
         {
             using ICacheEntry entry = cache.CreateEntry(key);
@@ -89,6 +157,14 @@ public static TItem Set<TItem>(this IMemoryCache cache, object key, TItem value,
             return value;
         }
 
+        /// <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>
+        /// <typeparam name="TItem">The type of the object to get.</typeparam>
+        /// <param name="cache">The <see cref="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>
+        /// <returns>The value associated with this key.</returns>
         public static TItem? GetOrCreate<TItem>(this IMemoryCache cache, object key, Func<ICacheEntry, TItem> factory)
         {
             if (!cache.TryGetValue(key, out object? result))
@@ -102,6 +178,14 @@ public static TItem Set<TItem>(this IMemoryCache cache, object key, TItem value,
             return (TItem?)result;
         }
 
+        /// <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>
+        /// <typeparam name="TItem">The type of the object to get.</typeparam>
+        /// <param name="cache">The <see cref="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>
+        /// <returns>The task object representing the asynchronous operation.</returns>
         public static async Task<TItem?> GetOrCreateAsync<TItem>(this IMemoryCache cache, object key, Func<ICacheEntry, Task<TItem>> factory)
         {
             if (!cache.TryGetValue(key, out object? result))