Document our Realm-Powered Swift Frameworks using DocC
Rate this article
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!
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
For example, these are line comments from
Package.swift: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!
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:
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:)
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 . 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 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:
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!
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.
Source code repo: https://github.com/mongodb-developer/realm-binary-tree