Swift Documentation Quick Guide

If you are a long time Objective-C developer you will be familiar with tools like HeaderDoc to annotate and create HTML documentation from your source code. Xcode Quick Help also displays the output during symbol completion.

Xcode QuickHelp

For Swift code Apple dropped HeaderDoc and switched to a Markdown style syntax. They chose the CommonMark variant of Markdown with some Swift specific keyword extensions. This quick guide covers what you need to know.

Symbol Documentation

There are four sections, of which, only the description is always included:

Description
Parameters
Throws
Returns

After the description the order of the other sections does not matter. You can only have one Throws and one Returns section.

Description

To start add a comment before the symbol (a function, class, instance variable, etc.) using either triple-slash single line comments or a comment block with a slash and two asterisks as follows:

/// Some introductory test that describes the purpose
/// of the function.

/**
 What does this function do?
*/

func someFunction(name: String) -> Bool {
  return false
}

You can include blank-lines between the comment and the symbol if you want. The appearance in Quick Help is below:

Basic description

Parameters Section

There are two ways to document parameters using either a parameters section or with individual parameter fields. The general format for all keywords is the same, start with a hypen and end with a colon. The keyword is not case-sensitive. The parameters section looks like this (note how you indent the parameter names from the top-level):

/**
 Another useful function
 - parameters:
   - alpha: Describe the alpha param
   - beta: Describe the beta param
*/
func doSomething(alpha: String, beta: String) {

Or with separate parameter keywords:

/**
 Another useful function
 - parameter alpha: Describe the alpha param
 - parameter beta: Describe the beta param
*/
func doSomething(alpha: String, beta: String) {

This produces the output:

Parameters

You can mix both styles and put them anywhere in the comment.

Throws Section

If you have a function or method that throws an error include a throws section:

/// Some introductory test that describes the purpose
/// of the function.
/// - Throws: SomeError you might want to catch

func someFunction() throws -> Bool {

Throws

Returns Section

Finally for a function or method that returns a value include a returns section:

/// Some introductory test that describes the purpose
/// of the function.
/// - Returns: true or false

func someFunction() throws -> Bool {

Returns

Keyword Quick Guide

If you want to get fancy there is a long list of keywords you can include anywhere in the description.

- Attention: Watch out for this!
- Author: Tim Cook
- Authors:
  John Doe
  Mary Jones
- Bug: This may not work
- Complexity: O(log n) probably
- Copyright: 2016 Acme
- Date: Jan 1, 2016
- experiment: give it a try
- important: know this
- invariant: something
- Note: Blah blah blah
- Precondition: alpha should not be nil
- Postcondition: happy
- Remark: something else
- Requires: iOS 9
- seealso: something else
- Since: iOS 9
- Todo: make it faster
- Version: 1.0.0
- Warning: Don't do it

Keywords

If that is not enough Xcode 7.3 adds keyword, recommended and recommendedover to the list.

Using Markdown

You can include any valid Markdown in the description. This is not a Markdown tutorial but here is a quick example with some headings, lists, a code block and link:

/// ---
/// # Subtitle 1
/// ## Subtitle 2
/// This is a *boring* list:
/// + First point
///   1. subpoint with **bold text**
///
/// Some code - indented by four spaces
///
///     let flag = someFunction()
/// ---
/// seealso: [Apple web site](www.apple.com)

Markdown