[generator] Add support for XML documentation in the API definitions. Fixes #17397.

[rolfbjarne]

• Enable generation of the documentation file (.xml) by the C# compiler when building projects (by passing the DocumentationFlag argument to the Csc task).
  • Also disable the CSC1591 warning, which complains about having public APIs without xml documentation; it just turns out to be annoying rather than helpful, since most APIs won't be documented.
• Add support in the generator for reading the .xml file next to the compiled api definition assembly, and then looking for documentation there when generating binding code.
  • When enabled, enable generation of the documentation file if the generator is compiling the api definitions.
  • Make it an opt-out, in case the new code causes problems.
• Add tests.

Fixes #17397.

[github-actions]

⚠️ Your code has been reformatted. ⚠️

If this is not desired, add the actions-disable-autoformat label, and revert the reformatting commit.

If files unrelated to your change were modified, try reverting the reformatting commit + merging with the target branch (and push those changes).

[vs-mobiletools-engineering-service2]

💻 [PR Build] Tests on macOS X64 - Mac Sonoma (14) passed 💻

✅ All tests on macOS X64 - Mac Sonoma (14) passed.

Pipeline on Agent
Hash: [PR build]

[vs-mobiletools-engineering-service2]

💻 [PR Build] Tests on macOS M1 - Mac Monterey (12) passed 💻

✅ All tests on macOS M1 - Mac Monterey (12) passed.

Pipeline on Agent
Hash: [PR build]

[vs-mobiletools-engineering-service2]

💻 [PR Build] Tests on macOS M1 - Mac Big Sur (11) passed 💻

✅ All tests on macOS M1 - Mac Big Sur (11) passed.

Pipeline on Agent
Hash: [PR build]

[vs-mobiletools-engineering-service2]

❌ [PR Build] Tests on macOS M1 - Mac Ventura (13) failed ❌

Failed tests are:

• monotouch-test

Pipeline on Agent
Hash: [PR build]

[vs-mobiletools-engineering-service2]

📚 [PR Build] Artifacts 📚

Packages generated

View packages

• xamarin.ios-17.3.0.249.pkg
• xamarin.mac-9.3.0.249.pkg

Pipeline on Agent
Hash: [PR build]

[vs-mobiletools-engineering-service2]

💻 [CI Build] Windows Integration Tests passed 💻

✅ All Windows Integration Tests passed.

Pipeline on Agent
Hash: 0a31116e19f54718391f7aa576a574c2b9cde7c9 [PR build]

[vs-mobiletools-engineering-service2]

✅ API diff for current PR / commit

Legacy Xamarin (No breaking changes)

• iOS (no change detected)
• tvOS (no change detected)
• watchOS (no change detected)
• macOS (no change detected)

NET (empty diffs)

• iOS: (empty diff detected)
• tvOS: (empty diff detected)
• MacCatalyst: (empty diff detected)
• macOS: (empty diff detected)

✅ API diff vs stable

Legacy Xamarin (No breaking changes)

• iOS: vsdrops gist (No breaking changes)
• tvOS: vsdrops gist (No breaking changes)
• watchOS: vsdrops gist (No breaking changes)
• macOS: vsdrops gist (No breaking changes)

.NET (No breaking changes)

• iOS: vsdrops gist (No breaking changes)
• tvOS: vsdrops gist (No breaking changes)
• MacCatalyst: vsdrops gist (No breaking changes)
• macOS: vsdrops gist (No breaking changes)
• Microsoft.iOS vs Microsoft.MacCatalyst: vsdrops gist

Legacy Xamarin (stable) vs .NET

• iOS: vsdrops gist
• tvOS: vsdrops gist
• macOS: vsdrops gist

ℹ️ Generator diff

Generator Diff: vsdrops (html) vsdrops (raw diff) gist (raw diff) - Please review changes)

Pipeline on Agent
Hash: 0a31116e19f54718391f7aa576a574c2b9cde7c9 [PR build]

[vs-mobiletools-engineering-service2]

💻 [PR Build] Tests on macOS M1 - Mac Ventura (13) passed 💻

✅ All tests on macOS M1 - Mac Ventura (13) passed.

Pipeline on Agent
Hash: [PR build]

[vs-mobiletools-engineering-service2]

🚀 [CI Build] Test results 🚀

Test results

✅ All tests passed on VSTS: test results.

🎉 All 170 tests passed 🎉

Tests counts

✅ cecil: All 1 tests passed. Html Report (VSDrops) Download
✅ dotnettests (iOS): All 1 tests passed. Html Report (VSDrops) Download
✅ dotnettests (MacCatalyst): All 1 tests passed. Html Report (VSDrops) Download
✅ dotnettests (macOS): All 1 tests passed. Html Report (VSDrops) Download
✅ dotnettests (Multiple platforms): All 1 tests passed. Html Report (VSDrops) Download
✅ dotnettests (tvOS): All 1 tests passed. Html Report (VSDrops) Download
✅ framework: All 8 tests passed. Html Report (VSDrops) Download
✅ fsharp: All 7 tests passed. Html Report (VSDrops) Download
✅ generator: All 2 tests passed. Html Report (VSDrops) Download
✅ install-source: All 1 tests passed. Html Report (VSDrops) Download
✅ interdependent-binding-projects: All 7 tests passed. Html Report (VSDrops) Download
✅ introspection: All 8 tests passed. Html Report (VSDrops) Download
✅ linker: All 65 tests passed. Html Report (VSDrops) Download
✅ mac-binding-project: All 1 tests passed. Html Report (VSDrops) Download
✅ mmp: All 2 tests passed. Html Report (VSDrops) Download
✅ mononative: All 6 tests passed. Html Report (VSDrops) Download
✅ monotouch (iOS): All 11 tests passed. Html Report (VSDrops) Download
✅ monotouch (MacCatalyst): All 7 tests passed. [attempt 2] Html Report (VSDrops) Download
✅ monotouch (macOS): All 8 tests passed. Html Report (VSDrops) Download
✅ monotouch (tvOS): All 11 tests passed. Html Report (VSDrops) Download
✅ monotouch (watchOS): All 4 tests passed. Html Report (VSDrops) Download
✅ msbuild: All 2 tests passed. Html Report (VSDrops) Download
✅ mtouch: All 1 tests passed. Html Report (VSDrops) Download
✅ xammac: All 3 tests passed. Html Report (VSDrops) Download
✅ xcframework: All 8 tests passed. Html Report (VSDrops) Download
✅ xtro: All 2 tests passed. Html Report (VSDrops) Download

Pipeline on Agent
Hash: 0a31116e19f54718391f7aa576a574c2b9cde7c9 [PR build]