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]>

Author: 4 people

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)" />

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>

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>

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>

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>

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>

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,
     }
 }

src/libraries/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>

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,
     }

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>