Generate different documentation per platform about swift-doc HOT 2 OPEN

Thanks for writing this up, @kean. I agree that this is something we should do, and it's something I've been thinking about a lot. And when I say "thinking about", I actually mean "dreading". I think this may be one of the hardest problems we'll face, both in terms of programming and design.

A lot of this comes down to a fun aspect of Swift that lets you define conditional compilation blocks pretty much anywhere. You start to appreciate this complexity when you look at what we're doing in SourceFile.Visitor and see how that's manifested in our docs for Alamofire's NetworkReachabilityManager type. (I wouldn't say that our current treatment of this information is all that good).

On the programming side, we'll have to write new functionality to flatten out all of the conditional compilation contexts, collate them by platform and condition, and generate complete symbol graphs for each of the platforms. This will require us to write a parser to make sense of the compilation condition branch expressions.

On the design side, there are a lot of unanswered questions about how best to present this information. Compile different versions of the documentation for each platform, as I think you're suggesting? Put everything together and allow users to filter or toggle between different views? I'd love to hear a few proposals.

from swift-doc.

Compile different versions of the documentation for each platform, as I think you're suggesting? Put everything together and allow users to filter or toggle between different views?

I have a hunch that the type of the project will pretty much dictate which of these two is ideal. Projects that vend the same API for all platforms might benefit from a single bundle with a platform toggle for types that need it. Projects that have non-trivial differences between platforms with diverging types might prefer the separate doc bundle approach.

There are also more ways to go about this when using a unified documentation. For instance instead of a toggle per-type, the index page could be a sectioned list of APIs by platform, putting all shared types in a Shared or Common section—not sure if this is technically possible, just spitballing.

from swift-doc.