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,
   

   `var property`

   
   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:

/// Comment texts write here for each row

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

/**
Comment texts write here 
*/

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.

/// Generates user event driven alerts.
/// It used to displays an alert message to the user. It is extended from `UIAlertController`. This class replace the `UIAlertView` class for displaying alerts.
class Alert: UIAlertController {
}

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

/**
Displays alert over passed view controller with title, message and buttons. - Parameters:
- inController: InController over which the alert is presented. Should use self, or provide view controller name.
- title: Title of the alert
- message: Main message presented in the alert
- userAction: UserAction optional parameter, it invoked when user tap on particular button in
alert.
## Usage Example: ## ````
Alert.showAlertView(inController: presentingViewController, title: "Title of the Alert", message: "Main message presented in the alert")
````
**Note :** If you wants to handle user tap action then you must be use userAction parameter */
class public func showAlertView(inController: UIViewController, title: String, message: String, userAction: ((String) -> ())? = nil) {
}

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.
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.

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:

cd path_to_project_root_folder

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

jazzy --help

You should see something like this:

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:

jazzy --swift-version 2.3 --min-acl internal

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:

jazzy --min-acl internal

Vipuls-iMac:JazzyDemo yudiz$ j  azzy --min-acl internal Running xcodebuild
Parsing ViewController.swift (1/3)
Parsing AppDelegate.swift (2/3)
Parsing Alert.swift (3/3)
building site
jam out ♪♫ to your fresh new docs in `docs`

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: