Fix API documentation

[rolfbjarne]

We currently don't have any sort of API documentation in .NET, and we'd like to fix this. Historically the documentation story for iOS has been rather complicated, where on one hand we had some manually written documentation for some of the most important iOS API, and then on the other hand we'd run a program on user's machine to import Apple's documentation that they shipped with Xcode. There were numerous problems with this approach (it was a complicated implementation and hard to maintain, it took a long time to execute on user's machines, it broke fairly often in the IDE, etc.), and it finally died when Apple changed how they stored their documentation on disk and the import tool stopped working (around Xcode 9 iirc).

Now we want to:

• Ship at least some sort of API documentation.
• Make the process simpler on our side (if it's easier to maintain, it's easier to make sure it doesn't bitrot as well)

The main idea behind the new plan is to use inline XML (triple-slash) documentation instead of documentation in an external repo. Hopefully this will make it much easier for us to handle/write/add to the documentation, and it will get better over time instead of worse. Using inline XML documentation is also the direction most other Microsoft teams are going.

There are multiple steps to the plan:

• 1. Enable XML documentation in our source code and ship it #17395.
• 2. Figure out how to publish XML documentation on our website #17396.
• 3. Create tool to inject link to Apple's online documentation in our XML documentation #17398
• 4. Add support for XML documentation in the generator #17397.
• 5. Import our existing documentation from xamarin/apple-api-docs as triple-slash documentation. #17399.
• 6. Document our documentation process/workflow/guidelines #17401.

Relevant people outside our team:

• Dave Britch, to help figuring out how to publish the documentation to the web site.

Refs:

• Libraries APIs are fully documented using efficient workflows runtime#44969
• https://github.com/dotnet/maui/blob/main/docs/CodeDocumentationGuidelines.md
• https://github.com/xamarin/maccore/commit/e06c4fda779e5ab6d41116d59410d3871841b9a5
• [xharness] Don't test documentation, it's broken. #14373
• https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/

[sandyarmstrong]

Also documentation is not shipped with the workloads, so the IDE only shows useful help if you happen to have legacy Xamarin.Mac installed (and of course there are differences in those APIs).

#13614

[sandyarmstrong]

And of course there is also all of https://docs.microsoft.com/en-us/xamarin/mac/.