Documenting in Swift

We have no excuses: documenting our code has never been easier. Swift engineers have done an excellent job providing us with a pretty well known and easy way to keep our code documented: markdown language. I’ve made an infographic to give you the most useful tips to achieve this. What follows is a brief overview.
All we need to know can be synthesized in two things: how to format and how Swift organizes and shows your documentation.
How to format
We can make use of almost any markdown syntax to format our documentation in our Swift code: predefined headings, strong, italics, bulleted lists, numbered lists, links, embedded code, etc.
How Swift organizes and shows your documentation
Swift organizes our methods’ documentation using the following sections, in this order (we just need to use the correct keywords to activate the optional ones):
- Description (default): here we can specify A LOT of things: author(s), copyright, warnings, notes, version, etc.
- Parameters (optional)
- Returns (optional)
- Throws (optional)
For example:

Then formatted documentation is shown when Option-click our method or selecting the interrogation mark in the Utilities bar:

We can also separate our code with some comment tags:
- // MARK:
- // TODO:
- // FIXME:
For example:

This will be shown in the bar above our code:


Bonus
We can render our documentation in a beautiful way using Jazzy.
Let’s be honest, everyone should do it for the sake of our team members or the future self that would get in touch with our own code in some months from now.
