Document our Realm-Powered Swift Frameworks using DocC

#Introduction

In the previous post of this series we added Realm to a really simple Binary Tree library. The idea was to create a Package that, using Realm, allowed you to define binary trees and store them locally.

Now we have that library, but how will anyone know how to use it? We can write a manual, a blog post or FAQs, but luckily Xcode allowed us to add Documentation Comments since forever. And in WWDC 21 Apple announced the new Documentation Compiler, DocC, which takes all our documentation comments and creates a nice, powerful documentation site for our libraries and frameworks.

Let’s try it documenting our library!

#Documentation Comments

Comments are part of any language. You use regular comments to explain some specially complicated piece of code, to leave a reason about why some code was constructed in a certain way or just to organise a really big file or function (By the way, if this happens, split it, it’s better). These comments start with // for single line comments or with /* for block comments.

And please, please please don't use comments for things like

1
// i is now 0
2
3
i = 0

For example, these are line comments from Package.swift:

1
// swift-tools-version:5.5
2
3
// The swift-tools-version declares the minimum version of Swift required to build this package.

While this is a regular block comment:

1
/*
  File.swift
  
  Created by The Realm Team on 16/6/21.
*/

We’ve had Documentation Comments in Swift (and Objective C) since forever. This is how they look:

1
/// Single-line documentation comment starts with three /

1
/**
  Multi-line documentation
  Comment
  Block starts with /**
*/

These are similar in syntax, although have two major differences:

• You can write Markup in documentation comments and Xcode will render it
• These comments explain what something is and how it’s used, not how it’s coded.

Documentation comments are perfect to explain what that class does, or how to use this function. If you can’t put it in plain words, probably you don’t understand what they do and need to think about it a bit more. Also, having clearly stated what a function receives as parameters, what returns, edge cases and possible side effects helps you a lot while writing unit tests. Is simple to test something that you’ve just written how it should be used, what behaviour will exhibit and which values should return.

#DocC

Apple announced the Documentation Compiler, DocC, during WWDC21. This new tool, integrated with Xcode 13 allows us to generate a Documentation bundle that can be shared, with beautiful web pages containing all our symbols (classes, structs, functions, etc.)

With DocC we can generate documentation for our libraries and frameworks. It won’t work for Apps, as the idea of these comments is to explain how to use a piece of code and that works perfectly with libraries.

DocC allows for much more than just generating a web site from our code. It can host tutorials, and any pages we want to add. Let’s try it!

#Generating Documentation with DocC

First, grab the code for the Realm Binary Tree library from this repository. In order to do that, run the following commands from a Terminal:

1
$ git clone https://github.com/mongodb-developer/realm-binary-tree
2
$ cd realm-binary-tree

If you want to follow along and make these changes, just checkout the tag initial-state with git checkout initial-state.

Then open the project by double clicking on the Package.swift file. Once Xcode ends getting all necessary dependencies (Realm-Swift is the main one) we can generate the documentation clicking in the menu option Product > Build Documentation or the associated keyboard shortcut ⌃⇧⌘D. This will open the Documentation Browser with our library’s documentation in it.

As we can see, all of our public symbols (in this case the BinaryTree class and TreeTraversable protocol are there, with their documentation comments nicely showing. This is how it looks for TreeTraversable::mapInOrder(tree:closure:)

#Adding an About Section and Articles

This is nice, but Xcode 13 now allows us to create a new type of file: a Documentation Catalog. This can host Articles, Tutorials and Images. Let’s start by selecting the Sources > BinaryTree folder and typing ⌘N to add a new File. Then scroll down to the Documentation section and select Documentation Catalog. Give it the name BinaryTree.docc. We can rename this resource later as any other file/group in Xcode. We want a name that identifies it clearly when we create an exported documentation package.

Let’s start by renaming the Documentation.md file into BinaryTree.md. As this has the same name as our Doc Package, everything we put inside this file will appear in the Documentation node of the Framework itself.

We can add images to our Documentation Catalog simply by dragging them into Resources. Then, we can reference those images using the usual Markdown syntax ![](/image-name.png). This is how our framework’s main page look like now:

Inside this documentation package we can add Articles. Articles are just Markdown pages where we can explain a subject in written longform. Select the Documentation Package BinaryTree.docc and add a new file, using ⌘N. Choose Article File from Documentation. A new Markdown file will be created. Now write your awesome content to explain how your library works, some concepts you need to know before using it, etc.

#Tutorials

Tutorials are step by step instructions on how to use your library or framework. Here you can explain, for example, how to initialize a class that needs several parameters injected when calling the init method, or how a certain threading problem can be handled.

In our case, we want to explain how we can create a Tree, and how we can traverse it.

So first we need a Tutorial File. Go to your Tutorials folder and create a new File. Select Documentation > Tutorial File. A Tutorial file describes the steps in a tutorial, so while you scroll through it related code appears, as you can see here in action.

We need two things: our code snippets and the tutorial file. The tutorial file looks like this:

1
@Tutorial(time: 5) {
2
    @Intro(title: "Creating Trees") {
3
        How to create Trees
4
5
        @Image(source: seed-tree.jpg, alt: "This is an image of a Tree")
6
    }
7
8
    @Section(title: "Creating trees") {
9
        @ContentAndMedia() {
10
            Let's create some trees
11
        }
12
13
        @Steps {
14
            @Step {
15
                Import `BinaryTree`                
16
                @Code(name: "CreateTree.swift", file: 01-create-tree.swift)
17
            }
18
19
            @Step {
20
                Create an empty Tree object
21
                @Code(name: "CreateTree.swift", file: 02-create-tree.swift)
22
            }
23
24
            @Step {
25
                Add left and right children. These children are also of type `RealmBinaryTree`
26
                @Code(name: "CreateTree.swift", file: 03-create-tree.swift)
27
            }
28
        }
29
    }
30
}

As you can see, we have a first @Tutorial(time: 5) line where we put the estimated time to complete this tutorial. Then some introduction text and images, and one @Section. We can create as many sections as we need. When the documentation is rendered they’ll correspond to a new page of the tutorial and can be selected from a dropdown picker. As a tutorial is a step-by-step explanation, we now add each and every step, that will have some text that will tell you what the code will do and the code itself you need to enter.

That code is stored in Resources > code as regular Swift files. So if you have 5 steps you’ll need five files. Each step will show what’s in the associated snippet file, so to make it appear as you advance one step should include the previous step’s code. My approach to code snippets is to do it backwards: first I write the final snippet with the complete sample code, then I duplicate it as many times as steps I have in this tutorial, finally I delete code in each file as needed.

#Recap

In this post we’ve seen how to add developer documentation to our code, how to generate a DocC package including sample code and tutorials.

This will help us explain to others how to use our code, how to test it, its limitations and a better understanding of our own code. Explaining how something works is the quickest way to master it.

In the next post we’ll have a look at how we can host this package online!

If you have any questions or comments on this post (or anything else Realm-related), then please raise them on our [community forum(https://www.mongodb.com/community/forums/c/realm-sdks/58). To keep up with the latest Realm news, follow @realm on Twitter and join the Realm global community.

#Reference Materials

#Sample Repo

Source code repo: https://github.com/mongodb-developer/realm-binary-tree

#Apple DocC documentation

Documentation about DocC

#WWDC21 Videos

• Meet DocC documentation in Xcode
• Build interactive tutorials using DocC
• Elevate your DocC documentation in Xcode
• Host and automate your DocC documentation