Summary: Documentation for Swift packages with DocC

by @ralfebert · updated July 15, 2021
Xcode 13 & iOS 15
Advanced iOS Developers

DocC is a new documentation tool in Xcode 13 that extends the existing Markdown-based syntax for source code documentation. Besides API reference you can create articles and tutorials for your packages and generate a documentation archive. These can be read online and in the Xcode documentation browser:

Syntax

The syntax to write documentation for APIs using source comments is as before and a stub can be auto-generated using Code actions:

The Markdown syntax has a few extensions. For example, you can link to other symbols and articles with double backticks:

/**
  See also ``exampleFunc`` or ``ExampleType/exampleFunc``.
  This article might be interesting: <doc:ExampleArticle>
 */

↗ Writing Symbol Documentation in Your Source Files
↗ Markdown syntax

Documentation catalog

You can add a documentation catalog to your Xcode project to add articles and to group topics into sections:

Tutorials can be generated using a custom language using directives like @Tutorial() { ... }:

↗ Documenting a Swift Framework or Package
↗ Adding Structure to Your Documentation Pages
↗ Adding Supplemental Content to a Documentation Catalog
↗ Interactive Tutorials
↗ Elevate your DocC documentation in Xcode - WWDC 2021
↗ Build interactive tutorials using DocC - WWDC 2021

Example

There is an example project that demonstrates all the features:

↗ SlothCreator example project

Documentation archives

A .doccarchive can be built from Xcode or using the command line. It can be downloaded and opened in Xcode. They are automatically built for Swift packages and can be hosted online for browser-based access:

↗ Distributing Documentation to External Developers
↗ Host and automate your DocC documentation - WWDC21

Hosting a .doccarchive requires setting up url redirection. The example from Apple uses Apache and a .htaccess file. It doesn't seem to be possible to serve them using static pages only as of now:

↗ Running Xcode DocC without Apache Server
↗ Running Xcode DocC documentation via Apache locally on macOS

An analysis of the .doccarchive file format and a static HTML exporter tool:

↗ DocC: Archived and Analyzed