Xcode secrets: save time with context-sensitive help and documentation

How many times have you been looking at Swift or Objective-C code in Xcode and can’t remember what a framework method, argument, constant, etc. means? Did you know that help — full documentation — is just a keystroke away? Did you also know that you can add the same type of pop-up, context-sensitive help to your own code? Here’s how. Let’s say you’re looking at the following NSString class method and can’t remember exactly what the call does, what parameters it takes, and what is its return value:

Highlight the method name, parameter, even the enum, and then press the following key combination on your keyboard:

[command] + [control] + [shift] + [?]

      or, using key symbols:

⌘ ⌃ ⇧ ?

Here’s what you’ll see: a context-sensitive help/documentation popup. Note that I added the red lines to highlight content. The red highlighting is not what Xcode provides (click to enlarge):

Figure 1: Xcode framework context sensitive help and documentation.

So you immediately get information about the method, parameter, enum, even constant’s:

  • Declaration (formal language signature);
  • Description (textual explanation of the entity’s purpose);
  • Parameters (a full list of names and definitions);
  • Returns (the value returned by a method/function, if applicable);
  • Availability (what version of iOS that the entity became available in — and sometimes in what version it was deprecated);
  • Declared In (the framework which contains the entity); and,
  • More (generally, the formal definition of the entity with explanations and other links).

Check out what I get if I click on the “More Type Method Reference” link as shown in Figure 1 (click to enlarge):


Figure 2. Type Method Reference for NSString stringWithContentsOfURL.

This is the clincher: You can define the same type of context-sensitive help/documentation for your own code.

Swift
Here’s a Swift instance method I wrote for supporting a UICollectionView demo project. I added context-sensitive documentation just above the method signature:

Here’s what happens when I highlight the method name or parameter in Xcode and click ⌘ ⌃ ⇧ ? on the keyboard:

Figure 3. Swift context sensitive help for my own code.

Objective-C
Here’s an Objective-C instance method I wrote for supporting a threading demo project. I added context-sensitive documentation just above the method signature in the class’s header (.h) file:

For Objective-C context sensitive documentation to work properly in Xcode, you must place the documentation markup in a class’s header (.h) file. Here’s the method’s body in the code (.m) file:

Here’s what happens when I highlight the method name or parameter in Xcode and click ⌘ ⌃ ⇧ ? on the keyboard:

Figure 4. Objective-C context sensitive help for my own code.

It’s a nice fairy tale to talk about “self-documenting code,” but generally languages are still too cryptic and developers are too lazy to realize this lofty goal. The fact of the matter is that you may not remember a built-in call you used two weeks ago, and may not remember a piece of code you wrote yourself two weeks — or two years — ago. Documentation is very helpful, especially if the code you’re writing will be used and supported by other developers. You want code that is maintainable and extensible.

Please come back soon and I’ll more formally explain the markup available to you for writing iOS code with context-sensitive documentation. I hope you enjoyed this tutorial. Please leave a comment if you have questions or feedback. And please stay tuned for more iOS tutorials.

Author: Andrew Jaffee

Avid and well-published author, software engineer, designer, and developer, now specializing in iOS mobile app development in Objective-C and Swift, but with a strong background in C#, C++, .NET, JavaScript, HTML, CSS, jQuery, SQL Server, MySQL, Oracle, Agile, Test Driven Development, Git, Continuous Integration, Responsive Web Design, blah, blah, blah ... Did I miss any fad-based catch phrases? My brain avatar was kindly provided by http://icons8.com under a Creative Commons Attribution-NoDerivs 3.0 Unported license.

Leave a Reply

Your email address will not be published. Required fields are marked *