Create Apple-like Docs From Your Code Comments in Swift
An alternative and a complement for README files or GitHub pages
Before going in-depth about what DocC is, we need to understand what Doc Comments are.
Doc Comments (a.k.a. Documentation Comments) are comments on the code that serves as documentation proposed.
Usually, the IDEs can recognize these kinds of comments and show them in the quick-help menu (using the option-click on Xcode); additionally, some tools can read your comments and generate documentation, like files in HTML or Markdown.
Many tools allow you to do this. In this article, we will explore the Apple official tool, Swift-DocC.
How does the generated documentation look?
The documentation generated with DocC looks very similar to the official Apple Swift documentation; we can guess that Apple uses this same tool to create it.
The below example shows how you can take advantage of the doc comments inside Xcode.
The below example shows how you can see the documentation in an Xcode window, just like the Apple Documentation.
You can add text format, like bold, italics, and even code examples.
On Swift Playgrounds, you can add images, but that will be a topic for another article.
How to use the Doc Comments on Swift?
As you already know, you can add regular comments on Swift, using the double slash // for single-line comments and the /* */ for multiline comments.
The Doc Comments uses a slightly different syntax, the triple slash /// for single-line comments, and the /** **/ format for multiline comments.
The most basic example would be a property declaration.
As you can see, Doc Comments should be in the line before the declaration; you can document anything you can declare, like functions, methods, properties, classes, structures, enums, enums cases, etc.
But you don’t need to document variables that only exist inside functions since its whole lifecycle is readable at a glance.
Documenting Functions
The functions require more work because you may want to document the parameters, return values, and throw errors.
The above is an example of documentation for a function with two parameters. First, we have a description of the ‘function’ and then the documentation for each parameter. It is a standard way to add documentation for parameters; it is essential to follow the standards to allow Xcode to know that you are referring to a parameter.
However, it isn’t the unique standard way to document parameters; there is another way that could look cleaner when you have many parameters.
Now let’s take a look at the return and throw.
As you can see, it is as easy as adding the — Throws: or — Returns: followed by the description; the Return usually is the last thing on your doc-comment.
💡 Pro-Tip
You don’t need to remember the proper syntax to write the Doc Comments; with the short-cut option(alt) + cmd + /, Xcode will automatically add a template to document whatever is under the cursor.
You can use Markdown styles to add format in your comments, like text between asterisks for *italics*, double asterisks for **bold**, and add code blocks like Markdown.
Let’s see an example:
Yes, you can add emojis to the Doc Comments!
How to generate Documentation?
Now you have written your Doc Comment across your source code; you may be wondering how to take more advantage of them.
💡 Note
Swift-DocC requires Swift 5.5 and Xcode 13 or above.
On Xcode Menu, choose Product > Build Documentation.
Xcode will open a new window where you can see the documentation directly.
That’s it; you already have your project documentation along the Apple Documentation; you can open the documentation anytime again without building by the menu Help > Developer Documentation.
However, any good documentation needs a good Home Page!
On your project, go to your primary folder, click on File > New File, search for “Documentation Catalog”, and press Next.
Xcode will create a new documentation Catalog that you can access from the Sidebar and a template to write the overview of your framework. It will be the homepage of your documentation.
Swift-DocC can be an alternative and a complement for README files or GitHub pages; tell us what kind of documentation you prefer for your source code.
FAQ
Should I need to document everything?
You can document any you want, but Swift-DocC will only generate documentation pages for public and open stuff.
What are the alternatives for Swift-DocC?
Jazzy for documentation in HTML and Swift Doc, which supports HTML and Markdown compatible with GitHub Wiki, are great alternatives.
