DocC Tutorial for Swift : Getting Started

Learn how to automatically create documentation for Swift using DocC. By Mina H. Gerges.

5 (3) · 2 Reviews

Download materials
Save for later
Share

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.

A meme picture of a guy talking about creating a documentation document so you could have documentation of your documentation.

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.
Note: This tutorial assumes you’re comfortable with developing SwiftUI apps using Xcode. If you’re not familiar with SwiftUI, check out SwiftUI: Getting Started first. You need Xcode 13 installed to follow this tutorial.

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:

A demo for the Given With Love app displays a list of available gifts. User selects a gift, proceeds to the checkout process.

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.
Note: The GivenWithLove project implements focus management in SwiftUI using modifiers and wrappers like FocusState to help users navigate forms more effectively.
To learn more about dealing with focus management in SwiftUI, check out Focus Management in SwiftUI: Getting Started.

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.

Flowchart shows the Xcode steps to create DocC documentation

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

Note: To follow up with the next sections, you’ll need to review your knowledge of the Markdown language, which DocC transforms into rich documentation.
If you’re new to Markdown, Markdown: Syntax has what you need.

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.

Preview of the GivenWithLove DocC 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.

Preview of the CheckoutViewModel DocC documentation.

In the CheckoutViewModel description, click the CheckoutData link.

Two screenshots showing how to navigate from CheckoutViewModel to Checkout Data inside documentation

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.

CheckoutData action menu showing add documentation button.

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.

CheckoutData before and after adding the description

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

DocC window displays the options available for validation search query.

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.

Preview of Validation enum documentation with the first method undocumented.

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.

Preview of Validation enum documentation in Documentation window.

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

Preview of isValid method documentation in documentation window

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.