Unidoc 0.20 Released!

Swift Documentation
1

hi Swifties! (is it too late to open these announcements with Happy New Year?)

anyway, Unidoc 0.20 is now available, and below i’m going to outline some of the most exciting improvements to our Swift documentation engine.

Deprecating the FNV-1 suffix (“DocC hashes”)

FNV-1 hashes are one of the oldest pain points of Swift Documentation, and Unidoc 0.20 ships with a greatly empowered symbol link syntax that allows you to write human-readable link disambiguations in virtually all scenarios where FNV-1 hashes would have been previously required.

How powerful is it?

As a pilot run, I migrated nine libraries to the human-readable link syntax, purging scores of FNV-1 hashes in the process.

  1. swift-bson
  2. swift-dom
  3. swift-grammar
  4. swift-hash
  5. swift-ip
  6. swift-jpeg
  7. swift-json
  8. swift-png
  9. swift-unixtime

We also updated all of the markdown sources for the articles on the SwiftOnServer website to use the new disambiguation syntax, eliminating a huge number of FNV-1 hashes there as well.

Although we anticipate there are still cases where FNV-1 hashes are necessary, so far we have not encountered a single instance of an ambiguous symbol link that could not be rewritten using the human-readable syntax.

We’ve previously pitched the base syntax on Forums, but these are the two main additions in Unidoc 0.20:

Disambiguating protocol requirements and default implementations

public 
protocol ExampleProtocol {
    func f()
}

extension ExampleProtocol {
    public
    func f() {}
}

As a straightforward extension to existing phylum-based disambiguation, you can now explicitly select protocol requirements using the [requirement] (or [requirement: true]) filter, or exclude them (thus preferring default implementations) using [requirement: false].

``ExampleProtocol.f [requirement]``
``ExampleProtocol.f [requirement: false]``

To use custom link text, you can replace the spaces in the links with hyphens to encode them with URI-friendly characters.

[custom text](ExampleProtocol.f-[requirement])
[custom text](ExampleProtocol.f-[requirement:false])

Type signature disambiguation

It is now possible to disambiguate methods, initializers, subscripts, and properties using type signature disambiguation, which allows you to filter overloads by specifying partial type signatures. (This builds on work by @ronnqvist in DocC.)

``Int.init(_:) (Float)``
``Int.init(_:) (Double)``

You can omit irrelevant argument and return types using the underscore character (_), to provide only the types that are different between overloads.

``Example.f(x:y:) (_, String)``
``Example.f(x:y:) (_, Substring)``
``Example.f(x:y:) (_, _) -> (_, _)``
``Example.f(x:y:) -> (_, Int)``

Arrays, Dictionaries, Optionals, implicitly unwrapped Optionals, metatypes, generic types, variadics, tuples, closures, suppressed conformances, some and any protocol composition types, and parameter packs are all supported.

``Example.g(_:) ([Int])``
``Example.g(_:) ([Int: String])``
``Example.g(_:) ([Int: String].Type)``
``Example.g(_:) (Int...)``
``Example.g(_:) (Set<Int>)``
``Example.g(_:) (Int?)``
``Example.h(_:) (Int!)``
``Example.g(_:) (Dictionary<Int, Int>.Index)``
``Example.g(_:) (Sendable & CustomStringConvertible)``
``Example.g(_:) ((Int, Int))``
``Example.g(_:) ((Int) -> Int)``
``Example.g(_:) (~Copyable)``

Custom link text can be used by removing optional spaces and replacing structural spaces with hyphens (-).

[custom text](Int.init(_:)-(Float))
[custom text](Int.init(_:)-(Double))

Composing features

You can combine multiple disambiguation mechanisms by specifying filters after type signatures:

``Example.g(_:) (Int64, _) -> Int64 [static func]``

[custom text](Example.g(_:)-(Int64,_)->Int64-[static-func])

Do note that the latter is a valid markdown link (as the brackets and parentheses are balanced), the Swift Forums highlighter is just failing to highlight it correctly.

UCF symbol links are a superset of the DocC symbol link syntax, so your existing DocC links will just work when rendered with Unidoc.

You can read our recipe page for a progressive rundown on how to use the expanded link syntax:

Apple Developer-style documentation themes

The new Apple Developer-style documentation theme that was previously added to Swiftinit is part of the Unidoc 0.20 release.

image
image1097×777 57.8 KB

Installing Unidoc

We now distribute prebuilt binaries for a number of platforms, which are available as .tar.gz archives on the project GitHub README.

From there, you can get started with our guide:

Other Improvements

Notable Bugfixes

Next Steps

One common piece of feedback we’ve gotten so far is that Unidoc is a great documentation engine, but not a great tool for writing documentation. Although the local iteration story has made great strides in the past year, we are aware that many still feel that Unidoc is primarily a “deploy to server system” and that it imposes a lot of complexity on users who are simply interested in editing docs and previewing changes on their local machine.

In the next year, we intend to streamline the local editing experience, and enable authors to do more locally without necessarily taking on the responsibility of managing a long-lived local documentation database.

3 Likes