Swift and Objective-C documentation with Jazzy

3 minute read

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 ruby

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:

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")
    }
}

Pro tip: you can use the ⌥ (option) + ⌘ (command) + / while on the line of a class, struct, function, etc. to automatically add the 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 your 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://rynaard.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)

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

image

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.

image

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.

image

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.

Updated: