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..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,6 +20,7 @@ ms.date: 05/08/2024
| `AndroidEnableObsoleteOverrideInheritance`
_Added in .NET 8_ | `true` | An boolean property that specifies if bound methods that override `@Deprecated` Java methods are automatically marked as `@Deprecated`.
[Documentation](#androidenableobsoleteoverrideinheritance)|
| `AndroidEnableRestrictToAttributes`
_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.
[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.
[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.
[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..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,7 +27,8 @@ It is shared between "legacy" binding projects and .NET 5 projects.
- $([MSBuild]::EnsureTrailingSlash('$(OutputPath)'))$(AssemblyName).xml
+
+ $([MSBuild]::EnsureTrailingSlash('$(OutputPath)'))$(AssemblyName).xml
$(NoWarn);CS1573;CS1591
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
true
obsolete
+ true
$(EnableDiagnostics)
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..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
@@ -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 = () => $"""
+
+
+ {generateDocumentationFile}
+
+
+ """;
+ } 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)
{