.NET MAUI Platform-Specific API Docs Challenges

[jfversluis]

Right now the published API docs for .NET MAUI only contain the cross-platform layer. This is the same as it was/is for Xamarin.Forms. We never published the platform-specific APIs, which were largely renderers.

For .NET MAUI, there are some situations where users will need to consume types from the platform layers, such as providing a WKWebViewConfiguration object to Microsoft.Maui.Platform.MauiWKWebView on iOS, or manipulating a Microsoft.Maui.Platform.MauiWebViewClient on Android.

While mdoc can produce a docset that combines the xplat layer with the platform layer, the docs site doesn’t have a good way of viewing the resulting content. For .NET API docs, the docs site can switch between version (e.g. NET 6/7) and language (e.g. C#/F#). What it can’t do is switch between platform (e.g. iOS/Android) as well. With this limitation, combined cross-platform + platform API docs would look like:

• Microsoft.Maui.Platforms
  • MauiWebViewClient
  • MauiWKWebView
  • WindowExtensions

Obviously MauiWebViewClient is Android only, MauiWKWebView is MaciOS, and WindowExtensions is cross-platform, these are just examples, they can be substituted by other classes that are platform-specific and cross-platform.

Solution 1: add a remark to the inline docs

So then we’d require the inline code documentation (the "///" (triple slash)) documentation to point out that type X is only available on platform Y. However, there’s the additional complication that some platforms have identical type names (e.g. MauiBoxView) but different members within the types. That would become very unclear, very quickly.

Solution 2: each platform is a different docset

An alternative setup is possible whereby we’d have docsets for .NET MAUI on iOS, .NET MAUI on Android etc, and we’d be able to switch between versions (6/7). They’d be completely different docsets within the API browser, people will have to click back and forth between different sections on the website, but it would still be all published from one repo.

This is also not without its difficulties – which docset do the conceptual docs link into for xplat types? Essentials dealt with this by having a docset in the API browser listed as “Xamarin.Essentials Shared”. Regardless, there’s still a cost in going down this route.

Solution 3: add support for multi-targeting on the Docs website (request (internal link))

Another option is to request docs engineering to provide better support for multi-targeted APIs. This would probably be a longer-term investment and won't serve us in the timeframe we're looking for.

All things considered we're accepting right now that we only have the cross-platform docs available, which is the majority of our APIs anyway, and will make sure that we refine those to the best they can be.

We will continue to investigate and reevaluate our options in this regard, just putting this issue here to capture our current considerations for future reference.