Generate documentation using ‘Jazzy’ for Swift

Overview

In this blog we are going to learn about how to automatically generate documentation for your project, framework, pod or library written in Swift matching Apple’s official reference documentation without writing a single line of code outside Xcode.

Documenting the code is an extremely important task for every developer. It’s an actually part of development process. I would agree that writing proper and comprehensive documentation for every single properties (variables and constants), methods, functions, classes, structs, enums, protocols, extensions, and any other code structure or entity you can think of or anything else that exists in a project is not an easy job. Writing the proper documentation for:

  1. Detail description of the properties, methods and classes, also highlight specific conditions, provide some notes, gives usage example of code, cases or requirements for your functions that have to be noted somewhere.
  2. Gives description of input (parameters) values and output (returns) values of your method.
  3. Description are written in easy word to understand for other developers and also for you. When you revisit a project months or years after initial implementation you remember everything without forgotten.

For this produce professional documentation using Jazzy, which is an open source project developed by Realm Developers. Documentation generated in bunch of linked HTML, CSS and JS files which looks exactly like the Apple documentation.

Markdown syntax for commenting

Before producing professional documentation for your code, we must to know the common commenting Markdown Syntax basics. If you already know about it, you’re good to go ahead, and skip this steps.

Markdown syntax is using special characters for formatting a text, for adding resources (like links and images) and for having special blocks of text (code blocks, usage example, order and unorder list). Those characters are easy to remember. Here’s a list of the most common Markdown syntax:

  1. #text#: It makes the text a header, same use of the <H1>tag in HTML. Double “#” characters will result in <H2>header tag in HTML, and so on until the <H6>header tag in HTML.
  2. **text**: It turns the text into bold.
  3. *text*: It turns the text into italics.
  4. * text: It creates an unordered list of items, also known as a bullet list (space character must be between the asterisk and the text). You can also use either the “+” or the “-” character instead of the asterisk. To wrap list items with hanging indent use up to three spaces after the asterisk (or any of the other two) symbol.
  5. 1. text: It creates an ordered list of items (numbered list).
  6. [linked text](http://myblog-url.com): It turns the text into hyperlink.
  7. > text: It turns the text into a blockquote.
  8. If you want to add indentation, same use of the <pre> and </pre> tag in HTML, you need to add set of 4 space characters or 1 tab character.
  9. If you don’t want to mess with spaces or tabs, then include your code in backticks characters. For example,

    will result to this: var property
  10. Create blocks of code is to add four backtick symbols, then start to write your code in new line, and after the last line of code add another set of four backticks.

How to write comment in Swift?

In swift there are specific rules that should be followed when documenting any kind of entity. Each row shall start with 3 slashes(///) like the shown below:

or everything should be included in a code block like the shown below:

In swift there is support double slashes (//) will result in a commented line too, but they’ll be ignored by Xcode and they would not render any documentation at all.

Here I write comments for my own created “Alert” Class.

Multiline comments for methods with Markdown syntax for parameter description, usage example, block of codes and notes.

You can find a lot of information about Markdown syntax on the web and your first search will return back to you several related results. You’ll find excellent sources to read more about Markdown syntax example from here and here.

Code documentation previewed and accessed in xCode

The code documentation you write in Xcode can be previewed and accessed in Xcode by two different ways:

  1. By placing the cursor in the property, method or class name, and opening the Quick Help Inspector like.Screen_Shot_1
  2. By Option/Alt-Clicking to the name of a property, method, class, etc. The Quick Look preview will pop up right above or below the name like.Screen_Shot_2

Generating professional documentation

About Jazzy Tool

Jazzy is great open source tool that can produce an Apple-style documentation for your code written in Swift. Actually, Jazzy creates a bunch of HTML pages that can contain every part of your code along with the documentation you’ve written in it. It’s command-line utility/tool and it’s easy to be used.

How to install Jazzy Tool?

How Jazzy it works, I’m not interested in; please visit its page on the GitHub and you’ll find all the information you need actually an easy process:

  1. Open your Terminal by Spotlight searching or from Dock.
  2. Type a command: [sudo] gem install jazzy.
  3. Enter your system password.
  4. Wait for while done process.

If the installation fails, make sure you update your RubyGem to the latest version as the package itself requires Ruby 2 or greater. Some El Capitan or later mac os users had issues with gem so if you’re one of them instead of typing gem install in your terminal, type the following:

  1. Type a command : sudo gem install -n /usr/local/bin jazzy.
  2. Enter your system password.
  3. Wait for while done process.

If you’re missing some other dependencies such as CocoaPods installing jazzy will also pull those updates as well. The reason why the first command does not work is because of the new System integrity protection feature introduced in El Capitan which restricts even administrators from writing to /usr/bin. After the installation process is completed, you’re ready to use Jazzy documentation tool.

Demo app description

To make it easy to you to try Jazzy out, I’ve prepared a small app that you can download here. It contains source code and generated professional documentation what we were discuss earlier. It’s a really, simple and not that useful at the same time app. App will display only AlertView for user information, accept user input/action and displaying.

Now ready to generate documentation

I hoping that you’ve downloaded the app by now, let’s see how Jazzy is used. Initially, Navigate to your xCode project’s root folder in terminal using the cd command:

More about Jazzy tool, you can see more options are use with Jazzy by typing:

You should see something like this:
Screen_Shot_3

Additionally, if you don’t have the latest Swift version and you see no results by Jazzy, then you can simply specify the Swift version of your xCode supports by adding another parameter to the above:

Now type jazzy and require options, and sit back to wait until Jazzy finishes its tasks. However, this will not include classes or other structures that have not been marked as public. Therefore, if you want to include everything, just type this:

Navigate to your Xcode project root folder and you should see a completely new folder called docs. Inside there are a bunch of HTML, JS and CSS files but you should simply open index.html and the entire documentation should popup. Example is given below:

Screen_Shot_4

mm

Vipul Patel Sr. iOS Developer

I am Vipul, Sr. iOS developer at Yudiz Solutions Pvt. Ltd. - a leading iPhone App development company. I am very passionate about my work since I have started working as a coder. I am a hard core programmer by heart and love sharing my knowledge with others as it is well said "Power is gained by sharing knowledge, not hoarding it".

Comments are closed.

Top