[XABT] Allow disabling binding XML documentation - #12321
Open
jonathanpeppers wants to merge 3 commits into
Open
Conversation
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>
Contributor
There was a problem hiding this comment.
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.targetsto clear/assignDocumentationFilebased onGenerateDocumentationFile. - Default
GenerateDocumentationFiletotruefor 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
falsedisables generation, but the MSBuild logic treats any value other than the literaltrue(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.
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Android binding projects currently reassign
DocumentationFile, sodotnet packgenerates and includes XML documentation even when users try to disable it.Preserve the existing default by enabling the standard .NET SDK
GenerateDocumentationFileproperty for Android projects, while treating blank and other non-truevalues as an explicit opt-out. This also honors values set late inDirectory.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