SwiftBiome: Improved Module, Extension, and namespace annotations

hi all, over the past few days, SwiftBiome (formerly entrapta) has been undergoing some major changes in its internal architecture, in order to help it scale up to supporting many more packages and modules without confusing documentation users who may not have those modules imported.

as part of these changes, the swiftinit.org site now features module- and extension-origin annotations to help you better understand where a particular symbol came from.

for example, on the page for AsyncStream.Continuation, the module the symbol lives in (_Concurrency) now appears in the top-right corner of the introduction, opposite the symbol kind.

as it was previously located in the breadcrumbs navigator, which displayed a fully-qualified symbol name, this also has the benefit of saving valuable horizontal space in the top bar, which can be very helpful for readability on mobile screens.

cross-module extensions

when working with modules besides the standard library, it is very common for modules to extend other modules. this is completely orthogonal to the symbol path hierarchy, e.g. when a community module vends an extension on a standard library type.

as anyone who’s used the Apple standard library docs has probably experienced, this can be a double-edged sword, since it’s not always obvious that a symbol requires importing a completely different module or framework than the namespace it’s defined in.

when this situation occurs, the SwiftBiome docs will display the root namespace (extended module) first, followed by a slash (/), then the name of the module you must import to use that symbol.

in the following example, Optional.setOrWriteBuffer(_:) is an NIOCore extension on Swift.Optional, so its namespace annotation reads “ Swift / NIOCore”:

Screenshot from 2022-02-21 09-42-38

while this may not look like much on the surface, this is actually reflective of very important underlying changes aimed at improving SwiftBiome’s multi-module documentation support, which we will be announcing very soon.

as always, don’t forget to bookmark the site if you’re interested in the project!