Document generation using Jazzy for Swift

Many popular document generator doesn't support Swift at the moment. Doxygen, HeaderDoc, etc, though they are still helpful in generating documentation for Objective-C projects.

Overview

Jazzy is one of the easiest to generate beautiful documentation for Swift projects in apple doc styled formatting.

Documenting the code is extremely important for every developer. Following this practice can help in many ways:

• Code Readability — helps the developer understand the code, how to use it.
• Brings clarity upfront about what each function meant to be and purpose behind the same.
• Highlights the parameters and return values.
• Generates professional documentation using tools as Jazzy(almost all projects have this as one of the points out of handover checklist)

Adding comments in Xcode

In swift, there are specific rules that should be followed when documenting any kind of entity. You should refer to the Markup Guide for details.

Each row shall start with 3 slashes(///) like the shown below:

/// Comment here for each row

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

/**
Comment goes here
*/
-or-
Use Command+Option+/ a line above a function,enum etc to automatically generate comments styling.

For example, illustrated a function comments:

import UIKit
/// This is a class to contain utility methods
class Utility:NSObject {
/**
This function calculates the sum of two numbers
## Important Notes ##
1. Both parameters are **Integer** numbers.
- parameters:
- a: Integer one
- b: Integer two
- returns: Added sum of two integers
*/
func plus(a: Int, b: Int) ->Int {
return a + b
}
}

Then you Option-Click on the function’s name, here’s what the Quick Help will show:

Setup & Installation

Open terminal and type below command

sudo gem install jazzy

Enter the system password and wait until the process completes.

Go to the project folder

cd project_folder

You can set options for your project’s documentation in a configuration file, .jazzy.yaml by default. Create a .jazzy.yaml(for setting all configs) file using.

touch .jazzy.yaml 

Sample yaml config for doc generation is shared below. For a detailed explanation and an exhaustive list of all available options, run

jazzy --help config

# Ordered by output of `jazzy — help config`
output: ProjectName_Docs
clean: true
xcodebuild_arguments:
- -workspace
- YourWorkspaceName.xcworkspace
- -scheme
- YourSchemeName
- CODE_SIGNING_ALLOWED = NO
author: AuthorName
module: Folder Name where all code resides
module_version: 1.0
copyright: Copyright message here
readme: README.md 
exclude:  
  - Sources/File1.swift  
  - Sources/File2.swift
min_acl: internal
# Options : [apple | fullwidth | jony | DIRPATH]
# Which theme to use. Specify either ‘apple’ (default), one of the other built-in theme names, or the path to your mustache templates and other assets for a custom theme.Default: apple
theme: apple

All set to go, just type below command this will start generating the documentation.

jazzy

Once the process completes you will have docs files insides the “ProjectName_Docs”. Use finder to navigate inside and open index.html in your browser.

Sample Swift Project

Thanks for reading the article, hope this helps!!

— — — — — — Happy Documentation !!! — — — — — — —

Any further queries/suggestions please reach out to me on sumit16.kumar@gmail.com