Document our Realm-Powered Swift Frameworks using DocC
Rate this article
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!
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
For example, these are line comments from
While this is a regular block comment:
We’ve had Documentation Comments in Swift (and Objective C) since forever. This is how they look:
These are similar in syntax, although have two major differences:
- 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.
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!
If you want to follow along and make these changes, just checkout the tag
git checkout initial-state.
Then open the project by double clicking on the
Package.swiftfile. Once Xcode ends getting all necessary dependencies (
Realm-Swiftis the main one) we can generate the documentation clicking in the menu option
Product > Build Documentationor 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
TreeTraversableprotocol are there, with their documentation comments nicely showing. This is how it looks for
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 > BinaryTreefolder 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
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.doccand add a new file, using ⌘N. Choose
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 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
initmethod, 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
Tutorialsfolder 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:
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.
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!
News & Announcements
Realm Cocoa 5.0 - Multithreading Support with Integration for SwiftUI & Combine
Oct 19, 2022