Skip to content

Commit fa33edd

Browse files
ViktorHoferViktorHofer
authored
Fix UseCompilerGeneratedDocXmlFile default value (#106179)
* Fix wrong default for UseCompilerGeneratedDocXmlFile property * Suppress undocumented public APIs that went in since the switch got a wrong default * PR feedback (add warning) * React to System.Speech not having an intellisense xml file * Update Directory.Build.props * Update intellisense.targets * Remove property from private assembly * Suppress PNSE doc error for System.Speech
1 parent 5b921e2 commit fa33edd

File tree

21 files changed

+64
-10
lines changed

21 files changed

+64
-10
lines changed

‎Directory.Build.props‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -389,6 +389,8 @@
389389
<TreatWarningsAsErrors Condition="'$(TreatWarningsAsErrors)' == ''">true</TreatWarningsAsErrors>
390390
<!-- Warnings to always disable -->
391391
<NoWarn>$(NoWarn);CS8500;CS8969</NoWarn>
392+
<!-- Suppress "CS1591 - Missing XML comment for publicly visible type or member" compiler errors for private assemblies. -->
393+
<NoWarn Condition="'$(IsPrivateAssembly)' == 'true'">$(NoWarn);CS1591</NoWarn>
392394
<!-- Always pass portable to override arcade sdk which uses embedded for local builds -->
393395
<DebugType>portable</DebugType>
394396
<KeepNativeSymbols Condition="'$(KeepNativeSymbols)' == '' and '$(DotNetBuildSourceOnly)' == 'true'">true</KeepNativeSymbols>

‎eng/intellisense.targets‎

Lines changed: 15 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
<Project>
22

3+
<PropertyGroup>
4+
<UseCompilerGeneratedDocXmlFile Condition="'$(UseCompilerGeneratedDocXmlFile)' == ''">true</UseCompilerGeneratedDocXmlFile>
5+
</PropertyGroup>
6+
37
<PropertyGroup Condition="'$(UseCompilerGeneratedDocXmlFile)' != 'true'">
48
<IntellisensePackageXmlRootFolder>$([MSBuild]::NormalizeDirectory('$(NuGetPackageRoot)', 'microsoft.private.intellisense', '$(MicrosoftPrivateIntellisenseVersion)', 'IntellisenseFiles'))</IntellisensePackageXmlRootFolder>
59
<IntellisensePackageXmlFilePathFromNetFolder>$([MSBuild]::NormalizePath('$(IntellisensePackageXmlRootFolder)', 'net', '1033', '$(AssemblyName).xml'))</IntellisensePackageXmlFilePathFromNetFolder>
@@ -10,7 +14,7 @@
1014
<IntermediateDocFileItemFromIntellisensePackage>$(IntermediateOutputPath)$(TargetName).intellisense-package.xml</IntermediateDocFileItemFromIntellisensePackage>
1115

1216
<!-- Suppress "CS1591 - Missing XML comment for publicly visible type or member" compiler errors when the intellisense package xml file is used. -->
13-
<NoWarn Condition="'$(SkipIntellisenseNoWarnCS1591)' != 'true'">$(NoWarn);1591</NoWarn>
17+
<NoWarn Condition="'$(SkipIntellisenseNoWarnCS1591)' != 'true'">$(NoWarn);CS1591</NoWarn>
1418
</PropertyGroup>
1519

1620
<!-- Flow these properties to consuming projects for Microsoft.Internal.Runtime.DotNetApiDocs.Transport.proj to only
@@ -20,13 +24,23 @@
2024
<UseCompilerGeneratedDocXmlFile>$(UseCompilerGeneratedDocXmlFile)</UseCompilerGeneratedDocXmlFile>
2125
<IsPartialFacadeAssembly>$(IsPartialFacadeAssembly)</IsPartialFacadeAssembly>
2226
<IsPlatformNotSupportedAssembly Condition="'$(GeneratePlatformNotSupportedAssemblyMessage)' != ''">true</IsPlatformNotSupportedAssembly>
27+
<SuppressPlatformNotSupportedAssemblyDocXmlError>$(SuppressPlatformNotSupportedAssemblyDocXmlError)</SuppressPlatformNotSupportedAssemblyDocXmlError>
2328
</TargetPathWithTargetPlatformMoniker>
2429
</ItemDefinitionGroup>
2530

2631
<ItemGroup>
2732
<PackageDownload Include="Microsoft.Private.Intellisense" Version="[$(MicrosoftPrivateIntellisenseVersion)]" />
2833
</ItemGroup>
2934

35+
<!-- Warn if the docs team provided package doesn't have an intellisense file for a given library and the library explicitly
36+
opts out from using the compiler generated xml file. -->
37+
<Target Name="ValidateIntellisensePackageXmlFilePathExists"
38+
Condition="'$(UseCompilerGeneratedDocXmlFile)' != 'true' and
39+
'$(IntellisensePackageXmlFilePath)' == ''"
40+
BeforeTargets="CoreCompile">
41+
<Warning Text="The 'UseCompilerGeneratedDocXmlFile' property was set to '$(UseCompilerGeneratedDocXmlFile)', but the doc team doesn't provide a file for this assembly. Remove the 'UseCompilerGeneratedDocXmlFile' property to let the compiler generate the file." />
42+
</Target>
43+
3044
<!-- Prepare the intellisense package xml file by copying it to the project's intermediate folder and update its file timestamp.
3145
This is necessary so that all project outputs are newer than all project inputs. Directly copying from the intellisense package
3246
would violate that and break fast up-to-date check. -->

‎src/libraries/Common/src/System/Security/Cryptography/X509Certificates/X509CertificateLoader.cs‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,9 @@
1313
namespace System.Security.Cryptography.X509Certificates
1414
{
1515
[UnsupportedOSPlatform("browser")]
16+
#pragma warning disable 1591 // TODO: Document this API. https://github.com/dotnet/runtime/issues/105974
1617
public static partial class X509CertificateLoader
18+
#pragma warning restore 1591
1719
{
1820
private const int MemoryMappedFileCutoff = 1_048_576;
1921

‎src/libraries/Microsoft.Extensions.Http/src/DependencyInjection/HttpClientBuilderExtensions.cs‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -645,6 +645,7 @@ public static IHttpClientBuilder ConfigureAdditionalHttpMessageHandlers(this IHt
645645
return builder;
646646
}
647647

648+
#pragma warning disable 1591 // TODO: Document this API. https://github.com/dotnet/runtime/issues/105974
648649
public static IHttpClientBuilder AddAsKeyed(this IHttpClientBuilder builder, ServiceLifetime lifetime = ServiceLifetime.Scoped)
649650
{
650651
ThrowHelper.ThrowIfNull(builder);
@@ -703,6 +704,7 @@ public static IHttpClientBuilder RemoveAsKeyed(this IHttpClientBuilder builder)
703704

704705
return builder;
705706
}
707+
#pragma warning restore 1591
706708

707709
// workaround for https://github.com/dotnet/runtime/issues/102654
708710
private static void UpdateEmptyNameHttpClient(IServiceCollection services, HttpClientMappingRegistry registry)

‎src/libraries/Microsoft.Internal.Runtime.DotNetApiDocs.Transport/src/Microsoft.Internal.Runtime.DotNetApiDocs.Transport.proj‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,6 @@
2828
<Target Name="IncludeProjectReferenceCompilerGeneratedSecondaryOutputInPackage"
2929
DependsOnTargets="BuildOnlySettings;ResolveReferences">
3030
<ItemGroup>
31-
3231
<!-- Exclude private assemblies -->
3332
<ProjectReferenceCopyLocalPathNonPrivate Include="@(ReferenceCopyLocalPaths->WithMetadataValue('ReferenceSourceTarget', 'ProjectReference')->WithMetadataValue('IsPrivateAssembly', 'false'))" />
3433

@@ -41,13 +40,16 @@
4140

4241
<ItemGroup>
4342
<PartialFacadeCompilerGeneratedXmlDocFile Include="@(CompilerGeneratedXmlDocFile->WithMetadataValue('IsPartialFacadeAssembly', 'true'))" />
43+
4444
<PlatformNotSupportedCompilerGeneratedXmlDocFile Include="@(CompilerGeneratedXmlDocFile->WithMetadataValue('IsPlatformNotSupportedAssembly', 'true'))" />
45+
<!-- Allow libraries to temporarily suppress the PNSE error. -->
46+
<PlatformNotSupportedCompilerGeneratedXmlDocFile Remove="@(PlatformNotSupportedCompilerGeneratedXmlDocFile->WithMetadataValue('SuppressPlatformNotSupportedAssemblyDocXmlError', 'true'))" />
4547
</ItemGroup>
4648

47-
<Error Text="Compiler generated XML documentation files are missing data because partial facade assemblies aren't yet supported by the repo infrastructure. Consider removing the partial facade feature or setting the 'GenerateDocumentationFile' property to false in the project file. Assemblies: @(PartialFacadeCompilerGeneratedXmlDocFile->Metadata('Filename'), ', ')."
49+
<Error Text="Compiler generated XML documentation files are missing data because partial facade assemblies aren't supported by the repo infrastructure. Consider removing the partial facade feature. Assemblies: @(PartialFacadeCompilerGeneratedXmlDocFile->Metadata('Filename'), ', ')."
4850
Condition="'@(PartialFacadeCompilerGeneratedXmlDocFile)' != ''" />
4951

50-
<Error Text="Compiler generated XML documentation files are missing data because PNSE (platform not supported exception) assemblies aren't yet supported by the repo infrastructure. Consider removing the PNSE feature or setting the 'GenerateDocumentationFile' property to false in the project file. Assemblies: @(PlatformNotSupportedCompilerGeneratedXmlDocFile->Metadata('Filename'), ', ')."
52+
<Error Text="Compiler generated XML documentation files are missing data because PNSE (platform not supported exception) assemblies aren't supported by the repo infrastructure. Consider removing the PNSE feature. Assemblies: @(PlatformNotSupportedCompilerGeneratedXmlDocFile->Metadata('Filename'), ', ')."
5153
Condition="'@(PlatformNotSupportedCompilerGeneratedXmlDocFile)' != ''" />
5254
</Target>
5355

‎src/libraries/System.Net.Http/src/System.Net.Http.csproj‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44
<TargetFrameworks>$(NetCoreAppCurrent)-windows;$(NetCoreAppCurrent)-linux;$(NetCoreAppCurrent)-osx;$(NetCoreAppCurrent)-freebsd;$(NetCoreAppCurrent)-maccatalyst;$(NetCoreAppCurrent)-ios;$(NetCoreAppCurrent)-tvos;$(NetCoreAppCurrent)-browser;$(NetCoreAppCurrent)-wasi;$(NetCoreAppCurrent)-illumos;$(NetCoreAppCurrent)-solaris;$(NetCoreAppCurrent)-haiku;$(NetCoreAppCurrent)-android;$(NetCoreAppCurrent)</TargetFrameworks>
55
<AllowUnsafeBlocks>true</AllowUnsafeBlocks>
66
<DefineConstants>$(DefineConstants);HTTP_DLL</DefineConstants>
7+
<UseCompilerGeneratedDocXmlFile>false</UseCompilerGeneratedDocXmlFile>
78
</PropertyGroup>
89

910
<!-- DesignTimeBuild requires all the TargetFramework Derived Properties to not be present in the first property group. -->

‎src/libraries/System.Numerics.Tensors/src/System/NIndex.cs‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -91,8 +91,10 @@ public static NIndex FromEnd(nint value)
9191
return new NIndex(~value);
9292
}
9393

94+
#pragma warning disable 1591 // TODO: Document this API. https://github.com/dotnet/runtime/issues/105981
9495
public Index ToIndex() => checked((Index)this);
9596
public Index ToIndexUnchecked() => (Index)this;
97+
#pragma warning restore 1591
9698

9799
/// <summary>Returns the NIndex value.</summary>
98100
public nint Value

‎src/libraries/System.Numerics.Tensors/src/System/NRange.cs‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -121,12 +121,14 @@ public override string ToString()
121121

122122
private static void ThrowArgumentOutOfRangeException() => throw new ArgumentOutOfRangeException("length");
123123

124+
#pragma warning disable 1591 // TODO: Document this API. https://github.com/dotnet/runtime/issues/105981
124125
public static implicit operator NRange(Range range) => new NRange(range.Start, range.End);
125126

126127
public static explicit operator Range(NRange value) => new Range((Index)value.Start, (Index)value.End);
127128
public static explicit operator checked Range(NRange value) => new Range(checked((Index)value.Start), checked((Index)value.End));
128129

129130
public Range ToRange() => new Range(checked((Index)Start), checked((Index)End));
130131
public Range ToRangeUnchecked() => new Range((Index)Start, (Index)End);
132+
#pragma warning restore 1591
131133
}
132134
}

‎src/libraries/System.Numerics.Tensors/src/System/Numerics/Tensors/netcore/IReadOnlyTensor.cs‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,8 @@
55
using System.Collections.Generic;
66
using System.Diagnostics.CodeAnalysis;
77

8+
#pragma warning disable 1591 // TODO: Document this API. https://github.com/dotnet/runtime/issues/105981
9+
810
namespace System.Numerics.Tensors
911
{
1012
[Experimental(Experimentals.TensorTDiagId, UrlFormat = Experimentals.SharedUrlFormat)]
@@ -44,3 +46,5 @@ public interface IReadOnlyTensor<TSelf, T> : IEnumerable<T>
4446
bool TryFlattenTo(scoped Span<T> destination);
4547
}
4648
}
49+
50+
#pragma warning restore 1591

‎src/libraries/System.Numerics.Tensors/src/System/Numerics/Tensors/netcore/ITensor.cs‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@
44
using System.Buffers;
55
using System.Diagnostics.CodeAnalysis;
66

7+
#pragma warning disable 1591 // TODO: Document this API. https://github.com/dotnet/runtime/issues/105981
8+
79
namespace System.Numerics.Tensors
810
{
911
[Experimental(Experimentals.TensorTDiagId, UrlFormat = Experimentals.SharedUrlFormat)]
@@ -37,3 +39,5 @@ public interface ITensor<TSelf, T>
3739
new ref T GetPinnableReference();
3840
}
3941
}
42+
43+
#pragma warning restore 1591

0 commit comments

Comments
 (0)