There are some powerful documentation features of Xcode you may not be using and will make your life a lot easier. Take a look at the downloaded exercise file. Go ahead and run it like I have here. I wrote a simple app to turn on and off a matrix of lights. Stop the app. 

Looking at the ContentView code, It is hard to figure out what is going on. Click On LightbankView.  I’ve got a light bank up top and a Toggle buttonView below it that I made. One’s a model and one is a view. I might use elsewhere they are hard to add to the code. 

Option-Click the VStack. You get a popup that describes how a VSstack works. If you open the right sidebar and click the Help icon you see the same info again. If you option-click LightBank, you get very little, but you can change this. You see under the quick help Declared in. You can click that and go to the definition. 

Above the definition, you’ll add a special comment. Instead of two slashes, add three. Add the comment. 

/// A data structure for a row of lights 

 Hit Command-B to build the project. Click on the LightBank struct and the quick help shows your summary. 

Any time you add three slashes and text above a declaration, it shows up in the Quick Help summary. In Xcode 11, You can do this faster with a command-click.  Command-click BankState, and select Add documentation. You get a place marker for your summary. Add the following: 

/// A pattern of lights.

 As this is an enum, I might want the possible values, so I’ll add that.

Can be .allOn, .allOff, .evenOn or .oddOn.

Really that should be in the discussion, not the summary. Press return before Can. The comment appears on the next line. Add a dash between the triple slash and Can. Build again and check the Quick Help. Both the sidebar and the popup show the values in the discussion section of the quick help. 

 /// - Can be .allOn, .allOff, .evenOn or .oddOn.

You can format this too. For using code case on my enum values, I’ll use the reverse single quote found above the tab key. I can quote my values like this: 

 /// - Can be `.allOn`, .`allOff`, `.evenOn` or `.oddOn`.

Build and check it out. 

There are other callouts besides discussion. Head down to the init. Command-click and Add documentation to init. For methods with parameters you also get the parameters already listed for you. You can add these manually or use the Add parameter in Command-Click.  Add these comments: 

/// A data structure for a row of lights
/// - Parameter count: The number of lights in a row
/// - Parameter on: The pattern of lights in the row from `BankState`

I like having enum values handy, so I’ll finish this off with a copy and paste of the line above. 

 /// - Can be `.allOn`, .`allOff`, `.evenOn` or `.oddOn`.

Build again and head back to ContentView. 

Option-Click LightBank. You get the summary for the Struct.

Option-Click on count and you get the quick help for the initializer.

Your summary even shows in the code completion. add this: 

var moreLights = Lightban

Code completion has a summary. 

You can do a lot more formatting and even links with markup in quick help. Markup is also used in Playgrounds. Check out chapter 4 of my Swift Playgrounds Application Development course for a lot more you can do with markup.  

The Whole Code

You can look at the completed code for this project on GitHub here: