NEW: Join my free 100 Days of SwiftUI challenge today! >>

How to add Markdown comments to your code

Swift version: 5.1

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.

LEARN SWIFTUI FOR FREE I have a massive, free SwiftUI video collection on YouTube teaching you how to build complete apps with SwiftUI – check it out!

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

Similar solutions…

About the Swift Knowledge Base

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

Buy Pro Swift Buy Swift Design Patterns Buy Testing Swift Buy Hacking with iOS Buy Swift Coding Challenges Buy Swift on Sundays Volume One Buy Server-Side Swift (Vapor Edition) Buy Advanced iOS Volume One Buy Advanced iOS Volume Two Buy Advanced iOS Volume Three Buy Hacking with watchOS Buy Hacking with tvOS Buy Hacking with macOS Buy Dive Into SpriteKit Buy Swift in Sixty Seconds Buy Objective-C for Swift Developers Buy Server-Side Swift (Kitura Edition) Buy Beyond Code

Was this page useful? Let us know!

Average rating: 5.0/5