Exploring better documentation for Verifai with DocC
At Verifai we put a lot of value on our documentation. It’s one of the first resources developers have when they start working with our identity verification platform, so we want our documentation to be clear and precise.
Our documentation also goes into Verifai’s deeper concepts that allow for high levels of customizability. This is why we’re always looking for ways to improve our documentation with great examples and great imagery.
So when Apple introduced DocC during its yearly developer conference (WWDC) in 2021, we definitely couldn’t wait to take a look at it for ourselves.
The basics
DocC stands for Documentation Compiler and just like the name implies it lets you create documentation from (among other sources) the comments in your code.
You can compile it from Xcode just like code. This creates an archive that can be shared, hosted online or sent along with the framework. It also allows developers to add extra articles and tutorials that live alongside the comments in the code. The documentation also has the familiar Apple documentation look and feel.
DocC is planning to become open sourced later in 2021, which opens up further possibilities. We’re definitely curious to see how the community will react on this introduction.
Exploring DocC step-by-step with Verifai
So without further ado let’s explore DocC with Verifai’s iOS SDK. We have chosen the Verifai NFC framework to start with throughout this blog. Verifai’s NFC framework allows developers to perform NFC checks on compatible identity documents. It checks the validity of the ID and can read information from the NFC chip like the color image of the document holder.
To actually build the documentation, open Xcode 13 or higher and go to Product → Build Documentation.
Xcode’s built-in documentation viewer will now open.
Right now we haven’t made any special changes to our in-code comments to support all the features DocC provides, so it has a pretty basic look. But it’s nice to examine how it looks right now and later compare it with how it looks afterwards. This way, we have a clear idea how it changed after our improvements.
Adding an overview
Before we add an overview, it is important thing to keep in mind that only public and open items will be added to the documentation.
To add documentation to the DocC archive, add comments to the actual code using either three forward slashes (“///”) or a block comment (“/** */”).
The first comment line will be added as a small summary.
If you insert a line break and after that a new comment with additional text, it will be shown under the “Overview” heading. Take a look at the following example:
This will result in the following Framework Overview:
And the following Class Overview:
And furthermore, the Quick Help also gives more information:
You can also add markdown code blocks to the comment lines.
Which will result in:
Things are starting to look great. The documentation is now in a recognizable style. This will make it easier to process code as you can focus on the instruction and not on how the documentation works.
It even adapts to your theme to make it feel even more at home in your environment.
Will result in:
Adding additional information to your documentation
What if we want a section that explains the goal of the SDK and how it works globally?
1. Enter the documentation catalogue. It allows us to add articles to our documentation to explain broader concepts that seamlessly integrate with our documentation.
2. To add one, choose a place inside your project and add the file through the “New File” menu item.
3. Then scroll down and find the “Documentation Catalog” template.
You’ll then be able to see it in your file explorer.
By default a top level article will be generated for you.
A very cool thing is that this will combine your existing documentation topics with anything you add in the summary or overview.
So if we add some basic values like this:
In the end, it will look like this:
Now let’s give this section some love and add some images to make things a bit clearer. You can see how we can fill our documentation with rich images that make the understanding of the framework easier.
Adding and linking articles to your documentation
Next we can add more articles and link them together so that we can explain concepts in their own pages and thus keep things smaller and clearer. In our example we’ll add a “Result Processing” article and link it in our VerifaiNFC article. At the bottom we’ll link to the documentation of the result_processing.
Xcode autocompletion functionality will automatically help you find the right file. After linking this article, it will be automatically combined in the final result.
Add additional information to classes, enums and structs via Extensions
What if we want to give more information about a certain class, enum or struct? This is where Extensions come in. Extensions allow us to extend the code of a certain class, enum or struct to more than what is currently available in the code. This allows us to extend the comments in the code itself with articles and give our users better information while keeping our code files smaller.
Example
Let’s use the VerifaiNFCError enum as an example. It provides basic information about which failures occurred during the NFC scan. But what if we want to supply more detailed information about what went wrong and what a developer can do about it.
1. We go to new file again just like when we were adding an article, but this time we add an extension:
2. To link the extension to our enum we need to make sure the title symbol has the same name as the enum we want to give more information about. This links them together. So in our case, since we’re extending the VerifaiNFCError, we want it to look like this:
In the title we need to ensure we also link the framework, otherwise DocC will not link our extension. So in the top we start with the framework VerifaiNFC and use a forward slash to complete the link to VerifaiNFCError, resulting in VerifaiNFC/VerifaiNFCError. Xcode’s code completion will kick in and allow you to select the right class.
3. When going to VerifaiNFCError in the documentation it will then show what we added in our extension.
Leveraging DocC for own usage
With a few simple steps we’ve already leveraged DocC to improve our documentation inside of Xcode and make it feel more at home among other Apple documentation.
After compiling the documentation for the first time, it became clear to us that we could write more internal documentation. Since we develop SDKs for other organizations, our focus was always on providing excellent external documentation. DocC gives us the ability to connect both internal and external documentation, something we are very happy with.
Practical findings
Finally I’d like to mention some tips and tricks that I encountered while writing this blog.
● When using images only JPG, JPEG and PNGs seem to work. SVGs don’t give an error or a warning, but just don’t show up.
● When creating an extension, don’t forget to link the framework in the title as well! This can be done by typing the main class follower by a forward slash ‘/‘ and then the class to link to the extension.
● It’s also possible to create tutorials. We hope to touch up on this in a later blog.
● Currently there are questions about how easy it would be to host multiple documentation archives.
● DocC can also be integrated into the CI by its own xcodebuild command docbuild. We hope to explore this further in the future.
In closing
The ultimate goal of DocC is to be able to offer a uniform method of documentation to everyone. It reduces, as it were, the cognitive effort required to understand the documentation: in fact, every documentation is in the same (Apple’s) style.
Another benefit is the integration of internal and external documentation thanks to DocC. Documentation no longer needs to be maintained in two places. The ability to link different concepts is also a welcome addition.
On the other hand, it is still unclear how DocC will work with other platforms. At the moment it is very much focused on Apple’s own ecosystem. It is still uncertain whether we can integrate documentation for other platforms with DocC as well. Hopefully this question will be answered in the near future.
In summary, these developments are very promising and we look forward to further developments in the future.
Happy documenting!
Relevant WWDC videos
We hope to explore DocC more in the near future, especially closer to the release of iOS 15. But you don’t have to wait for that. Feel free to check out the relevant WWDC videos below.
● Meet DocC documentation in Xcode (23 min)
● Elevate your DocC documentation in Xcode (18 min)
● Build interactive tutorials using DocC (23 min)
● Host and automate your DocC documentation (14 min)
