Xcode Playgrounds are great for trying out code quickly, or testing out a new API or framework. They can also be a wonderful form of interactive documentation.

Today we'll look at a few ways we can write our own interactive docs using rich comments in Xcode Playgrounds.

One of the primary ways we'll turn our Playgrounds into documentation is through rich comments.

Playgrounds have two "markup" modes: raw vs. rendered. As their names suggest, each mode specifies whether Xcode should "render" rich comments in our Playground, or make them editable.

We'll begin by creating a new Playground. Then we'll select Editor > Show Rendered Markup to switch modes.

Right away, we can see the top comment changes from:

//: Playground - noun: a place where people can play

To this:

We can write our own rich comments by adding a : symbol after the // in any comment to convert it to a rich one. Neat!

Rich comments' Markup syntax is heavily inspired by Markdown. (It's basically just Markdown).

Apple has a syntax guide, but here's the idea:

//: We can write regular text, **bold** text or *italic* text.
//: ## Headers

We can include links in our rich comments:

//: A great [link](http://littlebitesofcocoa.com).

We can allow readers to navigate pages with some special links:

//: [Next](@next) or [Previous](@previous)

Or link to specific pages (names will need to be URL encoded):

//: [View Models](View%20Models)

We can even include images in our rich comments. We just need to first add them to our Playground's Resources group, then use Markdown's normal image syntax:

//: ![](playgrounds-rock.gif)