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) {