DocC-style API reference now available for NIOCore, _Concurrency, and Swift modules

happy valentine’s day everyone!

until now, we have not been able to generate API references for the standard library, since its doc-comments predate DocC and don’t follow its format exactly. as of today, the entrapta documentation engine now supports loading doc-comments written in the pre-DocC ad-hoc format that the standard library, and many libraries like SwiftNIO use, and can generate DocC-style API references from them!

to see an example of the output in action, visit: Swift.String

one of the major goals of entrapta is to provide permanent, tooling-friendly URLs that you can compute without an XCode installation. (see discussion here.) it uses the slash separator '/' exclusively for nested types; members use the dot '.' separator instead, which greatly cuts down on the need for '-swift-enum', '-swift-struct', etc. disambiguation suffixes.

for symbols that are truly overloaded, entrapta uses its full mangled name as a disambiguation parameter, which you should pass as a query parameter in the form:


unlike the opaque DocC disambiguation suffixes, this string is accessible to all tools that interact with Swift binaries, including tools like perf which were originally designed for C binaries.

the end goal is to support multi-package, multi-module API references, where you can navigate docs by following symbol links across module boundaries. currently, it is not possible to say, click through a link in NIOHTTP1 to get to the page for IOData, because IOData lives in NIOCore. and you can’t click through a link to UnsafePointer, because UnsafePointer lives in the Swift module.

as an experiment, the site currently hosts API references for 3 modules, which all support cross-module symbol links:

to test out this feature, try visiting /reference/swift-nio/niocore/eventloopfuture, and clicking through the links to standard library symbols in the pages for its members!

when building entrapta, i tried to make something that i myself would use in my day-to-day development. so please don’t hesitate to give feedback on how these docs could be improved!