How to add Markdown comments to your code

Swift version: 5.10

Paul Hudson @twostraws June 10th 2021

Swift has special syntax that lets you embed Markdown-formatted text into your source code, which gets parsed by Xcode and displayed in the Quick Help system pane. Using specially formatted code comments, you can document what parameters should be passed in, what the return value will contain, any errors that can be thrown, and more.

This documentation is not the same as the regular inline comments you add to particular code. These special comments are placed before your functions and classes and are used to show information in the Quick Help pane, as well as in the autocomplete popup, and are formatted so that both humans and Xcode can read them.

Markdown comments start with /** and end with */, like this:

/**
Call this function to grok some globs.
*/
func myGreatFunction() {
    // do stuff
}

In this text you can use a selection of Markdown formatting, as shown below:

Place text in `backticks` to mark code; on your keyboard these usually share a key with tilde, ~.
* You can write bullets by starting with an asterisk then a space.
    * Indent your asterisks to create sublists
1. You can write numbered listed by starting with 1.
1. Subsequent items can also be numbered 1. and Xcode will renumber them automatically.

# Headings start with a # symbol
If you need subheadings, use ##, ###, and so on.

If you want to write a link, [place your text in brackets](and your link in parentheses)
Write a *single asterisk* around words to make them italic
Write **two asterisks** around words to make them bold

If you’re using Xcode 13 or later, you can use double backticks to produce links inside DocC documentation, like this:

Make sure and avoid using ``badFunction()`` unless you enjoy problems.

Documentation keywords

Beyond using text to describe your functions, Swift lets you add special keywords that get displayed in the Quick Help pane. First, the Returns keyword lets you specify what value the caller can expect back when the function runs successfully.

- Returns: A string containing a date formatted as RFC-822

Next is the Parameter keyword. This lets you specify the name of a parameter and describe what it contains. You can include as many Parameter lines as you have parameters.

- Parameter album: The name of a Taylor Swift album
- Parameter track: The track number to load

Third is the Throws keyword, which lets you specify a comma-separated list of the error types that can be thrown by the function:

- Throws: LoadError.networkFailed, LoadError.writeFailed

There are others, but those three are the most useful when you’re just starting out. If you include more freeform text between the documentation keywords, it will just be flowed into the correct position in Quick Help.

Available from iOS 8.0 – learn more in my book Pro Swift