Documenting in Swift

Leandro Fournier
Jul 28, 2017 · 2 min read
http://blog.leandrofournier.com/swift/documentando-en-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):

  1. Description (default): here we can specify A LOT of things: author(s), copyright, warnings, notes, version, etc.
  2. Parameters (optional)
  3. Returns (optional)
  4. 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:

Click where the function appears
This navigation view will appear

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.

Leandro Fournier

Written by

I’m an iOS developer and musician. Love to learn, teach, program and play the piano.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade