One thing that I'm finding awkward with DocC is that it can't show information about compile-time conditional availability of APIs.
For instance, consider the function UnsafeRawPointer.loadUnaligned(fromByteOffset:as:). It's back-deployed, so the documentation tells me that it's available from iOS 8.0, macOS 10.0, etc. That's sufficient if you're writing an application which only needs to compile using the latest toolchain, and your main concern is your minimum deployment target (runtime API availability), but if you're writing a library which needs to support building with older toolchains, there's no information at all about when this symbol was introduced.
Instead, I need to go digging through swift evolution proposals to find out when this was introduced. In this case it's thankfully straightforward because the proposal is clearly named (0349-unaligned-loads-and-stores.md) and mentions the version of Swift it shipped in, but sometimes it's much less obvious.
it looks like the source declaration doesn’t have any availability annotations at all, so i’m surprised the Apple docs are displaying platform availability in the first place.
this problem is very similar to API availability on linux? . there isn't a good solution because the required source level information simply doesn't exist. (because the needed annotations aren't mandatory.)
perhaps we could add an availability attribute to it in the next swift release, though that wouldn't help anyone browsing docs for 5.8/9…
Yeah, we recently ran into someone asking about this same function and the issue is that it's marked @_alwaysEmitIntoClient without availability which means it's always available, IF you have a new enough SDK (toolchain on Linux) that has this definition. Adding an @available doesn't help because that conveys the runtime availability of the function and in fact adding this attribute to this specific function would make it worse because those targeting 5.2 for example couldn't use this function anymore. It would be nice for us to at least start documenting which Swift stdlib version introduced this function (at least on the source level via a comment or such to start out with) would alleviate some pain. Another availability adjacent attribute stating the SDK/toolchain availability of the function would be useful for documentation purposes for DocC and other documentation projects to present to readers.