From ec1a80d4155ce24f9b532d26ce5bda4001d6d263 Mon Sep 17 00:00:00 2001
From: Jonathan Peppers <jonathan.peppers@microsoft.com>
Date: Fri, 7 Aug 2026 14:48:33 -0500
Subject: [PATCH 1/3] [XABT] Allow disabling binding XML documentation

Honor GenerateDocumentationFile=false for Android binding builds and packages while preserving the existing default behavior.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
---
 .../msbuild-reference/build-properties.md     | 10 ++++
 .../Xamarin.Android.Bindings.Core.targets     |  3 +-
 ...soft.Android.Sdk.DefaultProperties.targets |  1 +
 .../BindingBuildTest.cs                       | 48 +++++++++++++++++++
 4 files changed, 61 insertions(+), 1 deletion(-)

diff --git a/Documentation/docs-mobile/binding-libs/msbuild-reference/build-properties.md b/Documentation/docs-mobile/binding-libs/msbuild-reference/build-properties.md
index e72e3cc63bc..a88853a8a65 100644
--- a/Documentation/docs-mobile/binding-libs/msbuild-reference/build-properties.md
+++ b/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 and included when packing the binding project.<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.
diff --git a/src/Xamarin.Android.Build.Tasks/MSBuild/Xamarin/Android/Xamarin.Android.Bindings.Core.targets b/src/Xamarin.Android.Build.Tasks/MSBuild/Xamarin/Android/Xamarin.Android.Bindings.Core.targets
index f90f4f9dcad..2b523c9d715 100644
--- a/src/Xamarin.Android.Build.Tasks/MSBuild/Xamarin/Android/Xamarin.Android.Bindings.Core.targets
+++ b/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)' == 'false' " />
+    <DocumentationFile Condition=" '$(DocumentationFile)' == '' and '$(GenerateDocumentationFile)' != 'false' and '$(_ComputeFilesToPublishForRuntimeIdentifiers)' != 'true' ">$([MSBuild]::EnsureTrailingSlash('$(OutputPath)'))$(AssemblyName).xml</DocumentationFile>
     <NoWarn Condition=" '$(DocumentationFile)' != '' ">$(NoWarn);CS1573;CS1591</NoWarn>
   </PropertyGroup>
 
diff --git a/src/Xamarin.Android.Build.Tasks/Microsoft.Android.Sdk/targets/Microsoft.Android.Sdk.DefaultProperties.targets b/src/Xamarin.Android.Build.Tasks/Microsoft.Android.Sdk/targets/Microsoft.Android.Sdk.DefaultProperties.targets
index 27d8a47aae4..715928b89e5 100644
--- a/src/Xamarin.Android.Build.Tasks/Microsoft.Android.Sdk/targets/Microsoft.Android.Sdk.DefaultProperties.targets
+++ b/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>
diff --git a/src/Xamarin.Android.Build.Tasks/Tests/Xamarin.Android.Build.Tests/BindingBuildTest.cs b/src/Xamarin.Android.Build.Tasks/Tests/Xamarin.Android.Build.Tests/BindingBuildTest.cs
index 917737c0767..117f7fa0030 100644
--- a/src/Xamarin.Android.Build.Tasks/Tests/Xamarin.Android.Build.Tests/BindingBuildTest.cs
+++ b/src/Xamarin.Android.Build.Tasks/Tests/Xamarin.Android.Build.Tests/BindingBuildTest.cs
@@ -629,6 +629,54 @@ 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)]
+		[TestCase ("Pack", false)]
+		[TestCase ("Build", true)]
+		public void DisableDocumentationFile (string target, bool setInDirectoryBuildTargets)
+		{
+			var binding = new XamarinAndroidBindingProject ();
+			if (setInDirectoryBuildTargets) {
+				var directoryBuildTargets = binding.Imports.Single (import => import.Project () == "Directory.Build.targets");
+				directoryBuildTargets.TextContent = () => """
+					<Project>
+					  <PropertyGroup>
+					    <GenerateDocumentationFile>false</GenerateDocumentationFile>
+					  </PropertyGroup>
+					</Project>
+					""";
+			} else {
+				binding.SetProperty ("GenerateDocumentationFile", "false");
+			}
+			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)
 		{

From d1462a88fc769c6d561d8158da8bf1bd9c283686 Mon Sep 17 00:00:00 2001
From: Jonathan Peppers <jonathan.peppers@microsoft.com>
Date: Fri, 7 Aug 2026 14:52:42 -0500
Subject: [PATCH 2/3] [XABT] Require true for binding documentation

Treat blank and other non-true GenerateDocumentationFile values as disabling XML documentation generation.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
---
 .../Android/Xamarin.Android.Bindings.Core.targets |  4 ++--
 .../BindingBuildTest.cs                           | 15 ++++++++-------
 2 files changed, 10 insertions(+), 9 deletions(-)

diff --git a/src/Xamarin.Android.Build.Tasks/MSBuild/Xamarin/Android/Xamarin.Android.Bindings.Core.targets b/src/Xamarin.Android.Build.Tasks/MSBuild/Xamarin/Android/Xamarin.Android.Bindings.Core.targets
index 2b523c9d715..a193e716944 100644
--- a/src/Xamarin.Android.Build.Tasks/MSBuild/Xamarin/Android/Xamarin.Android.Bindings.Core.targets
+++ b/src/Xamarin.Android.Build.Tasks/MSBuild/Xamarin/Android/Xamarin.Android.Bindings.Core.targets
@@ -27,8 +27,8 @@ It is shared between "legacy" binding projects and .NET 5 projects.
   </PropertyGroup>
 
   <PropertyGroup Condition=" '$(_UseLegacyJavadocImport)' != 'true' ">
-    <DocumentationFile Condition=" '$(GenerateDocumentationFile)' == 'false' " />
-    <DocumentationFile Condition=" '$(DocumentationFile)' == '' and '$(GenerateDocumentationFile)' != 'false' 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>
 
diff --git a/src/Xamarin.Android.Build.Tasks/Tests/Xamarin.Android.Build.Tests/BindingBuildTest.cs b/src/Xamarin.Android.Build.Tasks/Tests/Xamarin.Android.Build.Tests/BindingBuildTest.cs
index 117f7fa0030..436c2852a8b 100644
--- a/src/Xamarin.Android.Build.Tasks/Tests/Xamarin.Android.Build.Tests/BindingBuildTest.cs
+++ b/src/Xamarin.Android.Build.Tasks/Tests/Xamarin.Android.Build.Tests/BindingBuildTest.cs
@@ -641,23 +641,24 @@ public void DocumentationFileGeneratedByDefault ()
 			FileAssert.Exists (documentationPath);
 		}
 
-		[TestCase ("Build", false)]
-		[TestCase ("Pack", false)]
-		[TestCase ("Build", true)]
-		public void DisableDocumentationFile (string target, bool setInDirectoryBuildTargets)
+		[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 = () => """
+				directoryBuildTargets.TextContent = () => $"""
 					<Project>
 					  <PropertyGroup>
-					    <GenerateDocumentationFile>false</GenerateDocumentationFile>
+					    <GenerateDocumentationFile>{generateDocumentationFile}</GenerateDocumentationFile>
 					  </PropertyGroup>
 					</Project>
 					""";
 			} else {
-				binding.SetProperty ("GenerateDocumentationFile", "false");
+				binding.SetProperty ("GenerateDocumentationFile", generateDocumentationFile);
 			}
 			using var builder = CreateDllBuilder ();
 			builder.Target = target;

From 7af2396f1760ccb0c18c772bccc99bbb6e738d0e Mon Sep 17 00:00:00 2001
From: Jonathan Peppers <jonathan.peppers@microsoft.com>
Date: Fri, 7 Aug 2026 15:46:22 -0500
Subject: [PATCH 3/3] Potential fix for pull request finding

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
---
 .../binding-libs/msbuild-reference/build-properties.md          | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/docs-mobile/binding-libs/msbuild-reference/build-properties.md b/Documentation/docs-mobile/binding-libs/msbuild-reference/build-properties.md
index a88853a8a65..da2939c8d78 100644
--- a/Documentation/docs-mobile/binding-libs/msbuild-reference/build-properties.md
+++ b/Documentation/docs-mobile/binding-libs/msbuild-reference/build-properties.md
@@ -20,7 +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 and included when packing the binding project.<br /><br />[Documentation](#generatedocumentationfile)|
+| `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