I've been really enjoying Swift-DocC so far, and one thing I particularly like are topics. The ability to group a set of related properties and methods in a logical group makes it a lot easier to organise larger APIs.
For example, in WebURL, I've grouped the members of the main
WebURL type: initialisers which parse URL strings are in one topic, URL components (
.path and the like) in another topic, and more detailed information about network hosts (such as
.origin) in another topic. This works really well:
Also really useful are the "see also" sections. They're great for referring to related functionality in a more prominent way than links in the body text. Declaring them is really easy; I just added the following to the documentation comment for the
username property to add its throwing setter equivalent,
setUsername, to the end of the document:
/// ## See Also /// /// - ``WebURL/setUsername(_:)`` ///
And it shows up with a nice, big reference that you'll notice even if you skim most of the body text . The rest of the section is filled with other items from the property's topic.
But they have a problem: they're not named, and I can't find any syntax which allows me to group these references in to named sections (I tried the regular
### Header sections; didn't work). DocC's guide doesn't mention "See Also" sections at all. Ideally, I'd have that section say "Responding to Setter Failures" rather than "Related Documentation", to really grab people's attention as they're taking a glance.
Now, I did find one workaround, but I'm unsure how wise it is. I can add these references as topics, and get the interface I wanted. For example, adding this to the
hostname documentation comment:
/// ## Topics /// ### Network Hosts and Origins /// /// - ``WebURL/host-swift.property`` /// - ``WebURL/Host-swift.enum`` /// /// ### Responding to Setter Failures /// /// - ``WebURL/setHostname(_:)`` ///
Produces exactly what I want. Users who view the
hostname property, will see in a really visible way that there's also this
host property which gives them more direct information, better suited to establishing a network connection. This is actually a snippet from the sibling topic "Network Hosts and Origins", filtered to only the declarations that are relevant here.
Unfortunately, things start to break when you build webs of topics in this way. It seems that arranging declarations in to topics establishes a level of hierarchy that's important to DocC's internal model, and cyclic topic references mean some symbols just don't show up.
The SwiftC guide mentions collections as a possible solution: by grouping large topics and having a way to refer to them from elsewhere, but it also warns against creating too much hierarchy.
So I have a few questions:
Is this an unwise use of Topics? The documentation describes them only as "groups with meaningful names", but it seems that DocC uses them for something else internally. Why can't I create cyclic topic references?
Is it possible to name groups in "See Also" so I don't need a full topic declaration?
Is it possible for a "See Also" section to refer to a topic other than splitting it out as a collection? In this case, I'd like the
WebURL.hostnameproperty, in the "Reading and Writing a URL's Components" topic, to have a "See Also" reference to the "Network Hosts and Origins" topic (also on the
WebURLtype). Ideally I'd also like to filter that reference to the most salient declarations.