[XABT] Allow disabling binding XML documentation

Documentation/docs-mobile/binding-libs/msbuild-reference/build-properties.md

@@ -20,6 +20,7 @@ ms.date: 05/08/2024
 | `AndroidEnableObsoleteOverrideInheritance`<br />_Added in .NET 8_ | `true` | An boolean property that specifies if bound methods that override `@Deprecated` Java methods are automatically marked as `@Deprecated`.<br /><br />[Documentation](#androidenableobsoleteoverrideinheritance)|
 | `AndroidEnableRestrictToAttributes`<br />_Added in .NET 8_ | `obsolete` | An enum-style property with valid values of `obsolete` and `disable` that specifies if the .NET `[Obsolete]` attribute is added to bound API that is marked with `@RestrictTo` in a Java library.<br /><br />[Documentation](#androidenablerestricttoattributes)|
 | `AndroidJavadocVerbosity` | `intellisense` | An enum-style property with valid values `intellisense` and `full` that specifies how "verbose" [C# XML Documentation Comments](/dotnet/csharp/codedoc) should be when importing Javadoc documentation within binding projects using the [`@(JavaSourceJar)`](build-items.md#javasourcejar) build action.<br /><br />[Documentation](#androidjavadocverbosity)|
+| `GenerateDocumentationFile` | `true` | A boolean property that specifies whether a C# XML documentation file is generated during build and (when packing) included in the produced NuGet package.<br /><br />[Documentation](#generatedocumentationfile)|
 
 ### AndroidBoundInterfacesContainConstants
 
@@ -94,6 +95,15 @@ It is extremely rare to need to change this property.
 
 Support for this property was added in .NET 8.
 
+### GenerateDocumentationFile
+
+A boolean property that specifies whether a
+[C# XML documentation file](/dotnet/csharp/language-reference/compiler-options/output#documentationfile)
+is generated and included when packing the binding project.
+
+XML documentation generation is enabled by default for binding projects. Set
+this property to `false` to disable XML documentation generation.
+
 ### AndroidJavadocVerbosity
 
 An enum-style property with valid values `intellisense` and `full` that specifies how "verbose" [C# XML Documentation Comments](/dotnet/csharp/codedoc) should be when importing Javadoc documentation within binding projects using the [`@(JavaSourceJar)`](build-items.md#javasourcejar) build action.

src/Xamarin.Android.Build.Tasks/MSBuild/Xamarin/Android/Xamarin.Android.Bindings.Core.targets

@@ -27,7 +27,8 @@ It is shared between "legacy" binding projects and .NET 5 projects.
   </PropertyGroup>
 
   <PropertyGroup Condition=" '$(_UseLegacyJavadocImport)' != 'true' ">
-    <DocumentationFile Condition=" '$(DocumentationFile)' == '' and '$(_ComputeFilesToPublishForRuntimeIdentifiers)' != 'true' ">$([MSBuild]::EnsureTrailingSlash('$(OutputPath)'))$(AssemblyName).xml</DocumentationFile>
+    <DocumentationFile Condition=" '$(GenerateDocumentationFile)' != 'true' " />
+    <DocumentationFile Condition=" '$(DocumentationFile)' == '' and '$(GenerateDocumentationFile)' == 'true' and '$(_ComputeFilesToPublishForRuntimeIdentifiers)' != 'true' ">$([MSBuild]::EnsureTrailingSlash('$(OutputPath)'))$(AssemblyName).xml</DocumentationFile>
     <NoWarn Condition=" '$(DocumentationFile)' != '' ">$(NoWarn);CS1573;CS1591</NoWarn>
   </PropertyGroup>
 

src/Xamarin.Android.Build.Tasks/Microsoft.Android.Sdk/targets/Microsoft.Android.Sdk.DefaultProperties.targets

@@ -51,6 +51,7 @@
     <_AndroidEmitLegacyInterfaceInvokers Condition=" '$(_AndroidEmitLegacyInterfaceInvokers)' == '' ">false</_AndroidEmitLegacyInterfaceInvokers>
     <AndroidEnableObsoleteOverrideInheritance Condition=" '$(AndroidEnableObsoleteOverrideInheritance)' == '' ">true</AndroidEnableObsoleteOverrideInheritance>
     <AndroidEnableRestrictToAttributes Condition=" '$(AndroidEnableRestrictToAttributes)' == '' ">obsolete</AndroidEnableRestrictToAttributes>
+    <GenerateDocumentationFile Condition=" '$(GenerateDocumentationFile)' == '' ">true</GenerateDocumentationFile>
 
     <!-- Mono components -->
     <AndroidEnableProfiler Condition=" '$(AndroidEnableProfiler)' == '' ">$(EnableDiagnostics)</AndroidEnableProfiler>

src/Xamarin.Android.Build.Tasks/Tests/Xamarin.Android.Build.Tests/BindingBuildTest.cs

@@ -629,6 +629,55 @@ public void JavaSourceJar ([Values (AndroidRuntime.CoreCLR, AndroidRuntime.Nativ
 			}
 		}
 
+		[Test]
+		public void DocumentationFileGeneratedByDefault ()
+		{
+			var binding = new XamarinAndroidBindingProject ();
+			using var builder = CreateDllBuilder ();
+
+			Assert.IsTrue (builder.Build (binding), "binding build should have succeeded");
+
+			var documentationPath = Path.Combine (Root, builder.ProjectDirectory, binding.OutputPath, $"{binding.ProjectName}.xml");
+			FileAssert.Exists (documentationPath);
+		}
+
+		[TestCase ("Build", "false", false)]
+		[TestCase ("Pack", "false", false)]
+		[TestCase ("Build", "false", true)]
+		[TestCase ("Build", "", true)]
+		public void DisableDocumentationFile (string target, string generateDocumentationFile, bool setInDirectoryBuildTargets)
+		{
+			var binding = new XamarinAndroidBindingProject ();
+			if (setInDirectoryBuildTargets) {
+				var directoryBuildTargets = binding.Imports.Single (import => import.Project () == "Directory.Build.targets");
+				directoryBuildTargets.TextContent = () => $"""
+					<Project>
+					  <PropertyGroup>
+					    <GenerateDocumentationFile>{generateDocumentationFile}</GenerateDocumentationFile>
+					  </PropertyGroup>
+					</Project>
+					""";
+			} else {
+				binding.SetProperty ("GenerateDocumentationFile", generateDocumentationFile);
+			}
+			using var builder = CreateDllBuilder ();
+			builder.Target = target;
+
+			Assert.IsTrue (builder.Build (binding), $"binding {target} should have succeeded");
+
+			var documentationPath = Path.Combine (Root, builder.ProjectDirectory, binding.OutputPath, $"{binding.ProjectName}.xml");
+			FileAssert.DoesNotExist (documentationPath);
+
+			if (target == "Pack") {
+				var packagePath = Path.Combine (Root, builder.ProjectDirectory, binding.OutputPath, $"{binding.ProjectName}.1.0.0.nupkg");
+				FileAssert.Exists (packagePath);
+				using var package = ZipHelper.OpenZip (packagePath);
+				Assert.IsFalse (
+					package.Any (entry => entry.FullName.EndsWith ($"/{binding.ProjectName}.xml", StringComparison.OrdinalIgnoreCase)),
+					$"{packagePath} should not contain an XML documentation file");
+			}
+		}
+
 		[Test]
 		public void AppWithSingleJar ([Values (AndroidRuntime.CoreCLR, AndroidRuntime.NativeAOT)] AndroidRuntime runtime)
 		{