Skip to content

[XABT] Allow disabling binding XML documentation - #12321

Open
jonathanpeppers wants to merge 3 commits into
mainfrom
jonathanpeppers-disable-binding-docs
Open

[XABT] Allow disabling binding XML documentation#12321
jonathanpeppers wants to merge 3 commits into
mainfrom
jonathanpeppers-disable-binding-docs

Conversation

@jonathanpeppers

Copy link
Copy Markdown
Member

Android binding projects currently reassign DocumentationFile, so dotnet pack generates and includes XML documentation even when users try to disable it.

Preserve the existing default by enabling the standard .NET SDK GenerateDocumentationFile property for Android projects, while treating blank and other non-true values as an explicit opt-out. This also honors values set late in Directory.Build.targets. Focused binding tests cover default build behavior, build and pack opt-outs, package contents, and a late blank value.

Full integration tests were not run locally because this worktree does not contain the required local .NET 11 Android SDK build.

Fixes #7762

  • Useful description of why the change is necessary.
  • Links to issues fixed
  • Unit tests

jonathanpeppers and others added 2 commits August 7, 2026 14:48
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>
Treat blank and other non-true GenerateDocumentationFile values as disabling XML documentation generation.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot AI review requested due to automatic review settings August 7, 2026 19:55

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR fixes Android binding projects always reassigning DocumentationFile (causing XML docs to be generated/packed even when users try to disable it) by pivoting to the standard .NET SDK GenerateDocumentationFile property as the opt-out switch.

Changes:

  • Update Xamarin.Android.Bindings.Core.targets to clear/assign DocumentationFile based on GenerateDocumentationFile.
  • Default GenerateDocumentationFile to true for Android projects to preserve existing behavior unless explicitly opted out.
  • Add binding-focused tests for default generation and build/pack opt-out, and document the property in binding MSBuild property docs.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File Description
src/Xamarin.Android.Build.Tasks/Tests/Xamarin.Android.Build.Tests/BindingBuildTest.cs Adds tests validating default XML doc generation and opt-out behavior for build/pack (including Directory.Build.targets scenarios).
src/Xamarin.Android.Build.Tasks/MSBuild/Xamarin/Android/Xamarin.Android.Bindings.Core.targets Gates DocumentationFile assignment/clearing on GenerateDocumentationFile to honor opt-out and avoid unwanted reassignment.
src/Xamarin.Android.Build.Tasks/Microsoft.Android.Sdk/targets/Microsoft.Android.Sdk.DefaultProperties.targets Sets GenerateDocumentationFile default to true to preserve existing Android project defaults while still allowing explicit opt-out.
Documentation/docs-mobile/binding-libs/msbuild-reference/build-properties.md Documents GenerateDocumentationFile for binding projects.
Suppressed comments (1)

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

  • This section says only false disables generation, but the MSBuild logic treats any value other than the literal true (including an empty value) as an opt-out. Documenting that behavior will help users avoid surprises.
[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.

Comment thread Documentation/docs-mobile/binding-libs/msbuild-reference/build-properties.md Outdated
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Unable to disable Javadoc (XML) generation during dotnet pack because of property reassignment

2 participants