DocC Tutorial for Swift : Getting Started

Before 2021, when Apple introduced DocC, you had two options for documenting your Swift package: You either wrote your documentation in your project’s readme file or used a third-party library like Jazzy to generate documentation from your code.

Jazzy was the simpler option, and the generated documentation would also match the look and feel of Apple’s official reference documentation. But what if there were an easier way to display your documentation right into the Xcode documentation window?

At WWDC 2021, Apple launched DocC, a documentation compiler that builds and views your documentation for Swift packages inside the Xcode documentation window. Apple expanded DocC’s functionality in WWDC 2022 so it can document Swift and Objective-C projects too.

DocC offers more advanced functionalities, such as publishing pre-built documentation to GitHub projects or adding catalog and extension files to app documentation.

In this tutorial, you’ll work on an app named Given With Love to learn about:

• Building Swift projects and Swift Packages documentation using DocC.
• Using symbols to connect items in your documentation.
• Adding a catalog to your documentation.
• Archiving and publishing the DocC documentation.

Getting Started

Click the Download Materials button at the top or bottom of this tutorial to download the starter project. Open GivenWithLove.xcworkspace in the starter directory in Xcode. Build and run on an iPhone simulator. You’ll see the following screen:

The app displays a list of available gifts. Select a gift, then enter shipping information. Finally, write a gift message along with the recipient’s email addresses.

In Xcode, look at the project navigator. It includes these two parts:

• GivenWithLove (Xcodeproj): The main project files which uses MVVM pattern.
• Given With Love Helper (Swift Package): A helper package for the project, such as extensions or custom views.

Notice how some of these files include documentation, while others don’t. You’ll document the remaining files in this tutorial before using DocC to build and archive the documentation.

But first, you need to understand how DocC works under the hood.

How DocC Works

DocC is a documentation compiler that transforms Markdown language into rich documentation.

While the Xcode builds your framework, it performs the following steps for creating DocC documentation:

1. Compiler saves details about any public APIs on your framework and generated code.
2. Compiler supplies DocC all the information about your public APIs.
3. DocC gathers the public API information and all other DocC’s option such as articles or tutorials available with your documentation catalog.
4. DocC produces the final archive containing the compiled documentation.

In the next section, you’ll build your first DocC documentation in the GivenWithLove app.

Building DocC Documentation

Open GivenWithLove.xcworkspace. Open the Product menu, and select Build Documentation.

Xcode starts building the documentation for a few seconds, and then the Developer Documentation window opens.

The project’s documentation appears on the left Navigator. It contains two sections for both the project and the Swift package documentation.

Here are some more options for building your DocC documentation in Xcode:

• The Shift-Control-Command-D shortcut builds the documentation right away.
• Set the value of Build Documentation During ‘Build’ from the Build Settings window to Yes. This option will build documentation every time you compile.
• Use the xcodebuild docbuild command in your CI pipeline or command-line. This performs the same function as setting Build Documentation During ‘Build’ in Build Settings to Yes.

Open the documentation window and expand the GivenWithLove project to see its contents. DocC supports initial grouping for your code, showing classes, structures and enumerations.

Select the search field up top and type CheckoutViewModel, then select the first menu option. See how DocC displays the documentation inside it.

In the CheckoutViewModel description, click the CheckoutData link.

Notice how this struct doesn’t have any documentation yet. This struct will be the first file you document in this project.

Documenting a Swift File

Open GivenWithLove.xcworkspace and then CheckoutData.swift. Command-click CheckoutData to open the action menu. Next, click Add Documentation. The Description placeholder appears above the struct declaration after three backslashes. Now, you’re ready to write this struct’s documentation.

There’s also a keyboard shortcut for this. You can put the cursor over CheckoutData, and press Command+Option+/. Alternatively, you can type /// on the line above the struct.

Replace the Description placeholder with the code below:

Checkout data needed to send a specific gift to a recipient's address and a gift message to the recipient's email.

This code produces the description that will appear below CheckoutData in the Documentation window.

Build the documentation. Select CheckoutData and you should see the description you just added.

Select the search field up top and type Validation, then select the option under the title Workspace Documentation.

The newly opened file is an enum inside the Given With Love Helper Swift package. Notice how all the methods inside this enum are documented except the first one. You’ll document it now.

Open Validation.swift inside the Given With Love Helper Swift package. Put the cursor on the first method, then press Command+Option+/. Xcode displays the available documentation placeholders for this enum, such as Description, Parameters and Returns.

Replace the placeholders with the code below:

/// Check if the input string is valid compared to the specified regex.
/// - Parameters:
///   - input: Input string under test.
///   - regex: The regex that compared to the input string.
/// - Returns: True if the input string is valid compared to the specified regex and false otherwise.

This code describes each detail of this method. It returns true when its input string matches against its input regex.

Build the documentation by changing the scheme to GivenWithLoveHelper and press Shift-Control-Command-D.

Expand GivenWithLoveHelper from the side navigator, then select the Validation enum. See how the above documentation appears under this enum’s first method.

Click isValid(input:with:) and see how it contains full details.

Now, you know how to create documentation using DocC. Next, you’ll learn to add a reference to a document that either belongs to your documentation or sits outside it.