Swift-DocC is Now Open Source

Franklin Schrans is a member of the Swift-DocC team at Apple.

At WWDC21, Apple announced Swift-DocC, a new documentation compiler for Swift frameworks and packages. Swift-DocC provides an effortless way to author great documentation alongside your code, and generate comprehensive documentation websites for Swift codebases. It supports API docs authored as code comments, long-form conceptual articles written in Markdown, and even step-by-step tutorials with integrated images.

Swift-DocC is included in the Xcode 13 tools, and people are already adding more documentation to their code. When it was announced at WWDC21, some of the engineers mentioned that Swift-DocC will be released as open source. And that day is now here, with support for multiple platforms.

Swift-DocC was developed with the following goals:

Overview

Swift-DocC encompasses tools and libraries to help developers write and generate documentation on many platforms, including macOS and Linux, with the goal to support all platforms with a Swift toolchain. The docc command line tool is already integrated in Xcode 13 and is architected in a way that can be integrated with other build systems such as SwiftPM. The open source project is composed of several components, some of which may be interesting in their own right for building other developer tools. The components include:

The tooling understands the Swift documentation comment syntax already popular within the Swift community in stand-out tools like Jazzy and SwiftDoc, and in IDEs like Xcode. It adds some novel syntax features, too. For example, the double-backtick ``SymbolName`` syntax creates links between symbols. An example:

Source file documentation comment

/// A model representing a sloth.
/// 
/// You can create a sloth using the ``init(name:color:power:)`` initializer, or
/// create a randomly generated sloth using a ``SlothGenerator``:
///
/// ```swift
/// let slothGenerator = MySlothGenerator(seed: randomSeed())
/// let habitat = Habitat(isHumid: false, isWarm: true)
/// do {
///     let sloth = try slothGenerator.generateSloth(in: habitat)
/// } catch {
///     fatalError(String(describing: error))
/// }
/// ```
public struct Sloth {  }

Rendered website

The rendered version of the Sloth page

What’s Next?

Integration with Swift Tools

Building documentation should be as easy as building code. To that end, among the next steps will be to include Swift-DocC with the core Swift tools, so all Swift developers can easily document their code from the very beginning of a project.

Like other components of the core Swift tooling, this project will follow the Swift Evolution process, with one of the first tasks being to design the integration with Swift Package Manager using extensible plug-ins. And soon, Swift development trunk snapshots (for a release after Swift 5.5) will include the Swift-DocC tools.

To read more about the future of Swift-DocC, check out the Swift-DocC project announcement post in the forums.

Adoption

To get started, generated documentation for the Swift-DocC project itself is hosted at swift.org/documentation. Longer-term goals include adding documentation to more packages, as well as migrating documentation for the standard library and other documentation across Swift.org. This will make it even easier for the community to participate in documenting and teaching Swift.

Get Involved

Your experience, feedback, and contributions are greatly encouraged!

Questions?

Please feel free to post questions about this post on the associated thread on the Swift forums.