Copy local intellisense xmls for assemblies with source of truth. (do…

…tnet#79134)

* Copy local intellisense xmls for assemblies with source of truth.

* use UseIntellisenseDocumentationFile instead

* Create intellisense.targets, which contains the Target that defines the set of files to copy, and the Target that copies each of those files into the artifacts/bin/docs folder.
The paths of the files to copy are dynamically defined depending if the assembly IsPackable property is set or not, and if the UseIntellisenseDocumentationFile boolean is set or not.

* Set UseIntellisenseDocumentationFile to true for the 3 assemblies that already have their source of truth in triple slash.

* Delete docs.targets, move package download to Build.proj

* Consume $(XmlDocDir) in Microsoft.NetCore.App.Ref.sfxproj

* Change condition to import intellisense.targets: Use $(IsSourceProject) == true

* Move XmlDocFileRoot to intellisense.targets, address suggestions for collecting xml file.

* Expand condition of CopyDocumentationFileToXmlDocDir to also check if IsNetCoreAppSrc == true.

* Change AfterTargets of CopyDocumentationFileToXmlDocDir from CoreCompile to CopyFilesToOutputDirectory

* Move PackageDownload to intellisense.targets

* Remove Choose+When. Readjust properties for Private.Intellisense files/folders. Fix conditions for doc file swap.

* Rename csproj property to something more clear.

* Default csproj property to true.

* Missed adding the "not previously set" condition for UseIntellisensePackageDocXmlFile in intellisense.targets.

* Remove incorrect condition in CopyDocumentationFileToXmlDocDir.

* Missed property reuse in Condition in sfxproj

* Only evaluate second IntellisensePackageXmlFile if the first one did not acquire any value.

* Move intellisense.targets import from root to libraries, right after the IsNetCoreAppSrc property is declared so we can use it.

* Enable CS1591, skip arcade warning

* Move SkipArcadeNoWarnCS1591 to src/libraries/Directory.Build.props to avoid coreclr failures

* Remove unnecessary slashes in sfxproj

* Move SkipArcadeNoWarn up to the top of src/libraries/Directory.Build.props to ensure it gets loaded before importing arcade.

* Revert Brotli and Vectors csproj changes. Those assemblies are either a partial facade or use PNSE.

* Add target to intellisense.targets that runs as InitialTarget of the current project, and throws errors if the UseIntellisensePackageDocXmlFile is set to false and the assembly is either a partial facade or uses PNSE.

* Improve error message: Mention the problematic property and the offending assembly.

* Added extra condition to verification target to only run when UseIntellisense... is not set to true.
Also moved the initial definition to its own solitary property group right before the verification target runs.

Rename the properties that acquire the value of a file path to "FilePath" instead of just "File", for clarity.

---------

Co-authored-by: smasher164 <[email protected]>
Co-authored-by: carlossanlop <[email protected]>

Build.proj

@@ -8,9 +8,6 @@
   </ItemGroup>
 
   <Import Project="$(RepositoryEngineeringDir)SubsetValidation.targets" />
-
-  <!-- Upfront restore hooks -->
-  <Import Project="$(RepositoryEngineeringDir)restore\docs.targets" />
   <Import Project="$(RepositoryEngineeringDir)restore\optimizationData.targets" Condition="'$(DotNetBuildFromSource)' != 'true'" />
 
   <Target Name="BuildLocalTasks"

Directory.Build.props

@@ -105,7 +105,6 @@
     <IbcOptimizationDataDir>$([MSBuild]::NormalizeDirectory('$(ArtifactsDir)', 'ibc'))</IbcOptimizationDataDir>
     <MibcOptimizationDataDir>$([MSBuild]::NormalizeDirectory('$(ArtifactsDir)', 'mibc'))</MibcOptimizationDataDir>
     <XmlDocDir>$([MSBuild]::NormalizeDirectory('$(ArtifactsBinDir)', 'docs'))</XmlDocDir>
-    <XmlDocFileRoot>$([MSBuild]::NormalizeDirectory('$(NuGetPackageRoot)', 'microsoft.private.intellisense', '$(MicrosoftPrivateIntellisenseVersion)', 'IntellisenseFiles', 'net'))</XmlDocFileRoot>
     <DocsDir>$([MSBuild]::NormalizeDirectory('$(MSBuildThisFileDirectory)', 'docs'))</DocsDir>
     <ManPagesDir>$([MSBuild]::NormalizeDirectory('$(DocsDir)', 'manpages'))</ManPagesDir>
 

eng/intellisense.targets

@@ -0,0 +1,51 @@
+<Project InitialTargets="VerifyAssemblySupportsDocsXmlGeneration">
+
+  <PropertyGroup>
+    <UseIntellisensePackageDocXmlFile Condition="'$(UseIntellisensePackageDocXmlFile)' == ''">true</UseIntellisensePackageDocXmlFile>
+  </PropertyGroup>
+
+  <Target Name="VerifyAssemblySupportsDocsXmlGeneration"
+    Condition="'$(UseIntellisensePackageDocXmlFile)' != 'true'">
+    <Error
+      Condition="'$(IsPartialFacadeAssembly)' == 'true'"
+      Text="The 'UseIntellisensePackageDocXmlFile' property is not supported for partial facade assemblies: $(AssemblyName)" />
+    <Error
+      Condition="'$(GeneratePlatformNotSupportedAssemblyMessage)' != ''"
+      Text="The 'UseIntellisensePackageDocXmlFile' property is not supported for assemblies that throw PlatformNotSupportedException: $(AssemblyName)" />
+  </Target>
+
+  <PropertyGroup>
+    <NoWarn Condition="'$(UseIntellisensePackageDocXmlFile)' == 'true'">$(NoWarn);1591</NoWarn>
+    <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="'$(UseIntellisensePackageDocXmlFile)' == 'true' and Exists($(IntellisensePackageXmlFilePathFromNetFolder))">$(IntellisensePackageXmlFilePathFromNetFolder)</IntellisensePackageXmlFilePath>
+    <IntellisensePackageXmlFilePath Condition="'$(IntellisensePackageXmlFilePath)' == '' and '$(UseIntellisensePackageDocXmlFile)' == 'true' and Exists($(IntellisensePackageXmlFilePathFromDotNetPlatExtFolder))">$(IntellisensePackageXmlFilePathFromDotNetPlatExtFolder)</IntellisensePackageXmlFilePath>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageDownload Include="Microsoft.Private.Intellisense" Version="[$(MicrosoftPrivateIntellisenseVersion)]" />
+  </ItemGroup>
+
+  <!-- TODO: Remove this target when no library relies on the intellisense documentation file anymore.-->
+  <!-- Replace the default xml file generated in the obj folder with the one that comes from the docs feed. -->
+  <Target Name="ChangeDocumentationFileForPackaging"
+          AfterTargets="DocumentationProjectOutputGroup"
+          Condition="'$(UseIntellisensePackageDocXmlFile)' == 'true'">
+    <ItemGroup>
+      <DocFileItem Remove="@(DocFileItem)" />
+      <DocFileItem Include="$(IntellisensePackageXmlFilePath)" />
+    </ItemGroup>
+  </Target>
+
+  <Target Name="CopyDocumentationFileToXmlDocDir"
+          AfterTargets="CopyFilesToOutputDirectory"
+          Condition="'$(IsNetCoreAppSrc)' == 'true' and '$(TargetFramework)' == '$(NetCoreAppCurrent)'"
+          DependsOnTargets="ChangeDocumentationFileForPackaging">
+    <Copy SourceFiles="@(DocFileItem)"
+          DestinationFolder="$(XmlDocDir)"
+          SkipUnchangedFiles="true"
+          UseHardlinksIfPossible="true" />
+  </Target>
+
+</Project>

eng/packaging.targets

@@ -28,9 +28,7 @@
     <GeneratePackageOnBuild Condition="'$(GeneratePackageOnBuild)' != 'true' and
                                        '$(BuildAllConfigurations)' == 'true' and
                                        '$(DotNetBuildFromSource)' == 'true'">true</GeneratePackageOnBuild>
-    <!-- Search for the documentation file in the intellisense package and otherwise pick up the generated one. -->
-    <LibIntellisenseDocumentationFilePath>$(XmlDocFileRoot)1033\$(AssemblyName).xml</LibIntellisenseDocumentationFilePath>
-    <UseIntellisenseDocumentationFile Condition="'$(UseIntellisenseDocumentationFile)' == '' and Exists('$(LibIntellisenseDocumentationFilePath)')">true</UseIntellisenseDocumentationFile>
+
     <!-- During NoBuild pack invocations, skip project reference build. Necessary for the IncludeProjectReferencesWithPackAttributeInPackage target. -->
     <BuildProjectReferences Condition="'$(NoBuild)' == 'true'">false</BuildProjectReferences>
   </PropertyGroup>
@@ -108,16 +106,6 @@
                                        ($(TargetFrameworks.Contains('$(NetFrameworkMinimum)')) or $(TargetFrameworks.Contains('net47')) or $(TargetFrameworks.Contains('net48')))" />
   </ItemGroup>
 
-  <!-- TODO: Remove this target when no library relies on the intellisense documentation file anymore.-->
-  <Target Name="ChangeDocumentationFileForPackaging"
-          AfterTargets="DocumentationProjectOutputGroup"
-          Condition="'$(UseIntellisenseDocumentationFile)' == 'true'">
-    <ItemGroup>
-      <DocumentationProjectOutputGroupOutput Remove="@(DocumentationProjectOutputGroupOutput)" />
-      <DocumentationProjectOutputGroupOutput Include="$(LibIntellisenseDocumentationFilePath)" />
-    </ItemGroup>
-  </Target>
-
   <!-- Add runtime specific file into the package if the tfm is RID specific. -->
   <Target Name="AddRuntimeSpecificFilesToPackage"
           DependsOnTargets="BuiltProjectOutputGroup;

src/installer/pkg/sfx/Microsoft.NETCore.App/Microsoft.NETCore.App.Ref.sfxproj

@@ -14,7 +14,7 @@
   <Target Name="AddFrameworkFilesToPackage" DependsOnTargets="ResolveLibrariesFromLocalBuild" BeforeTargets="GetFilesToPackage">
     <ItemGroup>
       <ReferencePath Include="@(LibrariesRefAssemblies)" />
-      <DocFilesToPackage Include="$(ArtifactsBinDir)/docs/%(LibrariesRefAssemblies.FileName).xml" Condition="Exists('$(ArtifactsBinDir)/docs/%(LibrariesRefAssemblies.FileName).xml')"/>
+      <DocFilesToPackage Include="$(XmlDocDir)%(LibrariesRefAssemblies.FileName).xml" Condition="Exists('$(XmlDocDir)%(LibrariesRefAssemblies.FileName).xml')"/>
       <Analyzer Include="$(MicrosoftNetCoreAppRefPackDir)/analyzers/**/*.*" />
       <FilesToPackage Include="@(Analyzer)" ExcludeFromValidation="true" TargetPath="analyzers/%(RecursiveDir)" />
     </ItemGroup>

src/libraries/Directory.Build.props

@@ -2,6 +2,11 @@
   <PropertyGroup>
     <SkipInferTargetOSName>true</SkipInferTargetOSName>
     <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 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>
   </PropertyGroup>
 
   <Import Project="..\..\Directory.Build.props" />

src/libraries/Directory.Build.targets

@@ -77,6 +77,7 @@
   </PropertyGroup>
 
   <Import Project="$(RepositoryEngineeringDir)versioning.targets" />
+  <Import Project="$(RepositoryEngineeringDir)intellisense.targets" Condition="'$(IsSourceProject)' == 'true'" />
 
   <!-- Libraries-specific binplacing properties -->
   <PropertyGroup>

src/libraries/System.Formats.Cbor/src/System.Formats.Cbor.csproj

@@ -3,6 +3,7 @@
     <TargetFrameworks>$(NetCoreAppCurrent);$(NetCoreAppPrevious);$(NetCoreAppMinimum);netstandard2.0;$(NetFrameworkMinimum)</TargetFrameworks>
     <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
     <IsPackable>true</IsPackable>
+    <UseIntellisensePackageDocXmlFile>false</UseIntellisensePackageDocXmlFile>
     <PackageDescription>Provides classes that can read and write the CBOR data format.
 
 Commonly Used Types: