NEW: Master Swift design patterns with my latest book! >>

How to add Markdown comments to your code

Written by Paul Hudson    @twostraws

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.

If you want to write a link, [place your text in brackets](and your link in parentheses)
# Headings start with a # symbol
## Subheadings start with ##
### Sub-subheadings start with ### and are the most common heading style you'll come across
Write a *single asterisk* around words to make them italic
Write **two asterisks** around words to make them bold

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

Did this solution work for you? Please pass it on!

Other people are reading…

About the Swift Knowledge Base

This is part of the Swift Knowledge Base, a free, searchable collection of solutions for common iOS questions.

Hacking with watchOS

Transfer your Swift skills to watchOS the easy way, and learn to build real-world apps in the process!

Click here to visit the Hacking with Swift store >>