Human readable alternative for DocC symbol link disambiguation

[taylorswift]

@taylorswift

which then brings us to the FNV-1 hashes, which solve problem #1, although there is still no way to discover the FNV-1 hash of a symbol you want to link to on linux. (XCode users are quite fortunate to have a tool to perform the hash lookup.)

in my opinion, the problem is that it is too difficult to look up the hashes of the declarations you want to link to. i think that designing and teaching a bespoke disambiguation syntax to avoid having to deal with hashes is not the right approach. we need to make the hashes easier to work with instead of trying to replace them with a more complex and less comprehensive alternative.

between now and last July when i posted this, i’ve discovered a few things about how the hashes behave that have led me to reach a different conclusion.

we’ve known for a while that DocC hashes basically force ABI stability on packages that might not actually have any ABI stability at all. for example, going from

func foo(x:__owned [Int])

to

func foo(x:consuming [Int])

is an API compatible change, but it is ABI breaking and therefore, also documentation-breaking.

i used to think this was only a hassle when making changes to packages, but as it turns out, this also prevents collaboration between developers contributing to the same version of a package on different platforms. because ABI is different on different platforms (duh.)

for a real-world example, consider Alamofire, which supports both linux and macOS. Alamofire contains many APIs that use symbols from Foundation, such as HTTPURLResponse, in DataStreamRequest.onHTTPResponse(on:perform:). the mangled name of HTTPURLResponse is different depending on what platform you are on, which means the DocC hash needed to reference that method is also different depending on what platform you are on.

practically, this means a project’s documentation must standardize on a “canonical platform”, (likely macOS) otherwise contributors will not be able to agree on a set of hashes to use. this makes it impossible for contributors on a different platform to write documentation for the package, as they have no way of knowing the right hashes to use.

(conversely, because i write packages for linux, this means that nobody on macOS can contribute to my packages, if they must update documentation when making changes.)

tooling improvements cannot realistically help in this situation, since the tooling would need to be able to generate the interfaces for a different platform and at that point you are close to just cross-compiling the package itself. which is challenging if you don’t have access to the necessary SDK.

---

TLDR; using FNV-1 hashes is the same as requiring all developers to contribute from the same platform, which is incompatible with a project’s goal of supporting multiple platforms.