Documenting Code in Xcode the Right Way

Xcode 7 onwards gave us the ability to document our code beyond just simple comments. Using Markdown, we can write structured documents that are both accessible right within Xcode’s Editor and as standalone documentation.

We can use this feature to document classes, functions, parameters, literally anything that we feel needs to be explained or referenced. This enables us to better share code with team members, or refer back in the future to what something does and why.

If your are writing API’s that will be used by other developers, documentation is a must!

To take full advantage of rich documentation you need to understand at least the basics of Markdown. Apple also has a reference document that you can read to understand which tags are supported and how to use them, I will not go over the markdown language specifics in this article.

Once you have documented code it will appear in the quick help inspector panel and in the code editor. Working through the example below will help demonstrate this.

There is a system of keywords than can be used to highlight particular parts of our code like parameters and returns. Here are a few examples,

  • Parameter someParameterName:
  • Returns:
  • Remark:
  • SeeAlso:
  • Todo:
  • Warning:
  • Version:
  • Author:
  • Note:

The names should explain their purpose, for example, we can put an author name in function documentation so we know who wrote it along with a version number.

Let’s try and example and see how this all works for our benefit.

Example Time

For this example I have created a very simple one screen application with one button, one text entry field, and one display label. Plus one function that gets called. Not exactly a viral app, but it serves our purpose for adding documentation.

I am going to use the keyboard shortcut inside the code editor to generate document block templates. To do this, all we need to do is place the cursor before the item we want to document. I’m going to start with the action for the button.

I’ll use the keyboard shortcut Command + Option + / and template code will be generated for me.

Now all I have to do is enter the information just as I would when filling in a functions parameters. Try to make your comments meaningful, try to describe the purpose of the code and what it will do.

I’ll repeat the process for the concatText function. This completes the documentation, I have included the code and generated documentation below.

If I now hold down the option key and click the cursor on the call to concatText in my button function, I get the following documentation.

So there is a simple example of creating code documentation. As you can see it is very useful if you were sharing code with a team and they needed to know what something does. We should all document our code, this just makes life a little easier for us and removes the excuses to not do it.

Standalone Documents

Using a 3rd party tool we can create standalone documentation that can be viewed in a web browser. To do this we need to install a tool called Jazzy. So let’s do that real fast.

Jazzy is a terminal tool. We need to install the Ruby gem, so at the terminal type

 

Now with the tool installed, navigate to the project folder that you want to generate documentation for and run Jazzy

 

To see available options for Jazzy and what they mean you can use the help system.

 

Jazzy should have created a folder called docs, in there will be the newly created documentation that you can open in any HTML viewer like a Web browser. You will see something along these lines as Jazzy is running

The Wrap

So that is a quick introduction to documenting code within Xcode. This is only the beginning of a beautiful journey to well-documented code, welcome aboard.

I have made a GitHub repository with this example for you to play around with, you can download it here.

Share Button