Symbol linking disambiguation help in warnings #346
Description
Feature Name
Symbol linking disambiguation help in warnings
Description
The adding of pretty arbitrary -9ytjf disambiguation suffixes to symbols is nearly impossible to guess right without using Xcode. And a large part of the server and other ecosystems are not using Xcode to develop their libraries, therefore the CLI experience must be improved so that docc is usable, regardless of IDE choice.
E.g.
``activateSingleton()-9ytjf``
rather than
``activateSingleton()``
for targeting
public protocol ClusterSingleton: DistributedActor where ActorSystem == ClusterSystem {
func activateSingleton() async
}
is nearly impossible to discover for non-Xcode developers.
Instead, we should offer additional notes accompanying the missing symbol warning;
DistributedActors.md:74:3: warning: Topic reference 'VersionVector' couldn't be resolved. No local documentation matches this reference.
// SOMETHING LIKE:
note: Did you mean one of these:
- activateSingleton()-9ytjf - ≤full symbol name here≥
Motivation
docc documentation must be editable regardless of source editor of choice of developers. We cannot rely only on autocompletion to form correct symbol links.
Importance
This is important for ecosystems where using Xcode is not assumed. A lot of the Swift on Server ecosystem developers who write a lot of great documentation and want to be using docc, are prevented from adopting it entirely since they must use Xcode to form correct links. Some of them may be using Linux, so just having an Xcode "handy" to write docc links is also not an option.
Alternatives Considered
No response