Along with unveiling Swift in 2014, Apple unveiled another quality feature in their development environment: Xcode playgrounds.
As well as helping me prove various points and experiment with code, playgrounds have helped me refamiliarise myself with Core Graphics and learn Core Animation. They show function outputs and even number of iterations executed on certain statements. Playgrounds work with iOS, OS X and tvOS, plus I've even heard proposals of developer books written entirely as playgrounds!
Apple enhanced playgrounds in 2015 by adding markdown documentation. But how do you add such documentation and bring your playgrounds to life?
First of all, if you're not familiar with markdown, this page on Daring Fireball is a quality primer. Trust me, you'll be grateful for it in many ways!
Next, create a new playground and clear out the sample code. Let's start by creating a single line example - to bring markdown to your single line comment, start your comment with //: - for example:
//: A *single* __line__ of markdown documentation
Now chances are you won't see any difference in your comment yet. You still have stars around "single" and two underscores on either side of "line" - let's change that! Open up the right pane and check "Render Documentation". The picture below sums this process all up:
Now you should have "single" in italics and "line" in bold. Now you can't edit markdown comments while they are rendered, so let's uncheck "Render Documentation" once again.
Prefixing lines with //: would get tedious if you did this for multiple lines. Thankfully, as is usual for comments in many programming languages including those natively supported by Xcode, you can do multiple line markdown comments too! This is especially useful if you want to add headers. To do this, simply start your comment with /*:.
/*: Multiple Line Example (this is not rendered)
# Hello, World!
*Multiple* __lines__ of
markdown documentation
*/
Enable comment rendering once again - you'll get a header showing "Hello, World!" then the text body with "multiple" in italics and "lines" in bold. "Multiple Line Example (this is not rendered)" does exactly what it says on the tin: it isn't rendered. Anything on the same line as the start of the comment is not rendered - this is useful for commenting your comments!
So, let's tie this all together. Rendering documentation with this playground code…
//: A *single* __line__ of markdown documentation
let answer = 42
/*: Multiple Line Example (this is not rendered)
# Hello, World!
*Multiple* __lines__ of
markdown documentation
*/
…generates something looking like this:
I hope you find this useful. For now though, happy documenting and playing 😀!