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.
-
/reference/swift/dictionary.keys(var Dictionary.keys) -
/reference/swift/dictionary/keys(struct Dictionary.Keys)
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:
"\(base)?overload=\(mangledName)"
-
/reference/swift/dictionary.merge(_:uniquingkeyswith:)?overload=s:SD5merge_16uniquingKeysWithyqd__n_q_q__q_tKXEtKSTRd__x_q_t7ElementRtd__lF(Dictionary.merge(_:uniquingKeysWith:))
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 swiftinit.org 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!