Swift and Objective-C documentation with Jazzy

Jazzy is a command-line utility that generates documentation for both Swift and Objective-C. Instead of parsing your source files, jazzy hooks into Clang and SourceKit to use the AST representation of your code and its comments for more accurate results. With a little bit of manual effort and some markdown goodness, you can generate great-looking HTML documentation using jazzy.

Installation

To install jazzy simply install the ruby gem:

sudo gem install jazzy

Adding code documentation

In order to have the documentation generated by jazzy you first need to add code documentation using Xcode’s documentation markup and/or standard markdown. Before getting started you might also want to have a look at the following resources:

• Xocde Markup Formatting Reference
• Markdown Cheatsheet by Adam Pritchard

The documentation you add to your source files will be used by jazzy in order to generate the HTML documentation. In the example below I have added code documentation for a class, struct, enum, and two functions, one of them being marked as deprecated:

/**
 A simple HTTP user client

 - Author:
 Rynaard Burger
 */

import Foundation

/// User HTTP client
public class UserApiClient {

    /// Representation of a user
    public struct User: Codable {
        let firstname: String
        let lastname: String
        let age: Int

        /// User status
        ///
        /// - active: User is active
        /// - blocked: User is blocked
        enum Status {
            case active, blocked
        }
    }

    /**
     Creates a new user
     - Parameter user: The new user

     ### Usage Example: ###
     ````
     UserApiClient.newUser(user1)
     ````
     */
    public static func newUser(_ user: User) {
        fatalError("not yet implemented")
    }

    /// Creates a new user (Deprecated)
    ///
    /// - Parameters:
    ///   - firstname: User firstname
    ///   - lastname: User lastname
    ///   - age: User age
    /// - warning: Deprecated. Use: `UserApiClient.newUser(_ user: User)`
    @available(*, deprecated, message: "Use newUser(_ user: User)")
    public static func newUser(firstname: String, lastname: String, age: Int) {
        fatalError("not yet implemented")
    }
}

You can also use the ⌥ (option) + ⌘ (command) + / keyboard shortcut while on the line of a class, struct, function, etc. to automatically add the code documentation for you.

Swift and Objective-C documentation is written in markdown but also supports a number of special keywords, some of which includes:

Swift:

• - warning
• - see
• - note

Objective-C:

• @warning
• @see
• @note

Generating the HTML documentation

Generating the documentation is really easy, just go to the folder where your Xcode project is located and run the following command:

jazzy

This will generate Swift documentation using the default options but you can actually do a whole lot more. You can always have a look at all the options available by running: jazzy -h.

For example, you can specify the author, link to the author’s website, link to a GitHub page etc:

Swift

jazzy \                                                                                  
--clean \
--author "Rynaard Burger" \
--author_url https://rynaardb.com \
--github_url https://github.com/rynaardb/jazzy-documentation

Objective-C

For Objective-C you must also pass the following parameters to jazzy:

• --objc
• --umbrella-header ...
• --framework-root ...
• --sdk [iphone|watch|appletv][os|simulator]|macosx (optional, default value of macosx)
• --hide-declarations [objc|swift] (optional, hides the selected language declarations)

jazzy \                                                                                  
--clean \
--author "Rynaard Burger" \
--author_url https://rynaardb.com \
--github_url https://github.com/rynaardb/jazzy-documentation \
--objc \
--umbrella-header \
--framework-root \
--sdk \
--hide-declarations

What you get is beautiful looking HTML documentation very similar to Apple’s official documentation. All with just a few lines of code documentation and markdown:

Other benefits

Another benefit of adding code documentation is that you also get full autocomplete and Quick Help support right in Xcode with no additional effort required.

To view the Quick Help you can use ⌥ (option) + right-click on a type or function, or alternatively you can also click on the “Show Quick Help inspector” button on the right in Xcode.

Summary

There is nothing worse than having to search through header files or actual implementation files just to figure out how things fit together. Having good documentation, especially for APIs or frameworks consumed by others, makes it so much easier to get started and to quickly figure out how everything is supposed to work together.

Using jazzy there is no excuse why you cannot have nice looking documentation with very little effort.

The example Xcode project can be found on my GitHub repository.