Like Joe pointed out; the short answer is that links across modules isn't supported out-of-the-box* and that it's something we're working on. There's a longer answer but I'll save that for last since I think your question is mostly focused around what the link syntax would be for referencing non-symbols in other modules.
The current link syntax
The syntax for general DocC documentation links (
<doc:> links) has two main components; an optional identifier—(the "host" component of the link) which isn't needed for local links—and a path to the page.
For authoring convenience DocC allow the developer to omit the leading path components of the path. For example; in the SlothCreator sample, all of these are links to the GettingStarted article:
(In the last 3 links, the documentation bundle identifier happens to be the same as the target module name)
The same behavior applies to tutorial content, where the tutorial overview page is another "root page" — meaning that the tutorial overview page is not a descendant of the module page.
In the SlothCreator example it would be possible to link to the tutorial overview as just
<doc:SlothCreator> except that that link is ambiguous because the tutorial overview page has the same name as the module and for historical reasons—which is a behavior we've kept for backwards compatibility—the module page is preferred over the tutorial overview page in this collision. If you rename the file to "MeetSlothCreator.tutorial" you can link to it using
<doc:MeetSlothCreator>. Without renaming it,
<doc:tutorials/SlothCreator> is the shortest path that unambiguously refers to the tutorial overview page.
Today we have more options for disambiguating links, so you should also be able to write
<doc:SlothCreator-tutorial> but when I tested it just now that doesn't work so I need to look into that.
How that applies to external links
If we do nothing more to the documentation link syntax, then the way you would reference an external article in the current syntax would be something along the lines of
Of course, you'd need some way to get make the external content available to DocC, which there isn't an out-of-box-solution for today.
Resolving links across targets today
Resolving links between modules isn't supported out-of-the-box. That said, if you really, really want to do this today, you can.
All the way back since the initial open source release, DocC has had the infrastructure to bridge with other documentation systems with one feature to resolve links to external systems and one feature to expose all the pages and landmarks of the DocC content that other systems can link to.
This system is primarily meant to bridge with other documentation systems and it wasn't originally designed for other DocC content. Because of this, you'll be working against the API in some cases trying to use it to resolve external DocC content. It has gotten better over the last year but there are still one or two obstacles in the design that make this harder to do than it should be.
I've been hoping to deprecate that system at some point but we'd need something to replace it with. Whether or not DocC content would have its own integration or if everything would go through the same system is still not decided.
So, if anyone really, really wants to do this today, you can message me about it—or post in this Forum thread or something—and I can provide some pointers on how to get set up and what code you'll need to write for your documentation bridge. Just know that you'd be using a feature that we're working on replacing.