Both methods have an identical symbol path of SlothCreator/Sloth/update(_:) . In this scenario, and to ensure uniqueness, DocC uses the symbol’s unique identifier instead of its name to disambiguate. Use Xcode’s code completion feature — which you can invoke by pressing the Escape key or Control-Space — when adding the symbol link to insert the correct identifier for each symbol.
The easiest way to get the disambiguation suffix on Linux is probably to build the docs, browse to the page you want to link, and copy the suffix from the web url.
It'd be neat to integrate with Swift's LSP server to provide documentation link autocomplete in VSCode etc but that's a non-trivial project.
The browsing the previews definitely works best when you only need one or two, but I recently ran into needing the whole kit to help me provide a list of all the symbols and organize them into some sane collection.
@ethankusters turned me on to adding the --emit-digest flag when running a docc convert command, which generates an extra JSON file that includes all the linkable entities for your module.
I think hacked together some bash one-liners, sed, and such to extract the symbol names and extensions from that collection:
^ every element of the collection has a referenceURL, so I extracted all those into a text file. They're the full documentation reference URL though (symbol is a sub-part of that) - so look something like doc://YourLibrary.bundle.id/documentation/SlothCreator/...
Then I just went crazy with sed to search and replace away the portions I didn't care about, and add in the prefixes to make them all look like a collection of symbols (the -``somethign`` format):
sort all_identifiers.txt \
| sed -e 's/doc:\/\/YourLibrary\.bundle\.id\/documentation\///g' \
| sed -e 's/^/- ``/g' \
| sed -e 's/$/``/g' > all_symbols.txt