Properly using XCode Quick Help

Luke, 22 Jan 2019

Creating explanations of classes or functions via comments is sometimes a necessity, but I often its not done in a way that works properly with XCodes own built-in Quick Help functionality. Heres how to do that properly.

Theres two ways that XCode provides for you to supply documentation to anyone reading your code. The first is via a larger markdown block that you would normally place above the implentation of a class, struct or other larger code block. This is denoted with a /** at the start and a */ at the end. Using this format, your explanation will appear both at the tooltip, and on the right pane in Quick Help. Heres an example, for a class defined just below this, called MapKitRouteStep (tested in XCode 10.1)

/**
 A single step within a larger route
 
 Contains all the information required to describe a single route step, 
 from the start and end points to the instructions at the end of the step, 
 and the polyline to draw it on a map.
 
 ## Parameters ##
 - startPoint: the 2d location of the starting point of this step
 - endPoint: the 2d location of the ending point of this step

 */

class MapKitRouteStep {
    var startPoint : CLLocationCoordinate2D! {
        return self.polyline.coordinates.first!
    }

This means that alt-clicking on any instance of this class in code pops up this very informative little box, nicely formatted :

In addition, in the right pane on XCode you can select to see the Quick Help pane which also gives you the same info whenever an instance of this class is clicked on :

Important to note here : the formatting of this documentation block is quite particular. If you look at the first two lines in the original markdown above : the top line becomes the text under ‘Summary’, and then, and only if you leave a line in between this and the second line – then the second line of text becomes the text for ‘Discussion’. Without the carriage return in-between those two, the second line of text does not get used as ‘Discussion’.

Beyond that, I used ## markdown syntax to denote a further title for a section, and then a standard * to denote bullet point. There is much more detail available on the markdown language available for use in XCode documentation, but I found this was plenty enough for nice looking documentation.

The second way to provide comments that will appear in XCode tooltip and quick help, is to use a triple forward slash before comments, like this :

///represents the 2d coordinate at the start of this step
var startPoint : CLLocationCoordinate2D! {
   return self.polyline.coordinates.first!
}

This will add the description you have provided to the tooltip and quick help, like this :

One final point on this. You dont see commenting like this, and thorough explanation of classes, structs, enums etc., as something that is required in coding standards, or picked up on in a code review. For me though its sign of a really throughly created piece of code, and I’ll be looking to include it in coding standards from now on.