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:
|
1 |
NSString *result = [NSString stringWithContentsOfURL:url encoding:NSUTF8StringEncoding error:&error]; |
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):
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):
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:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 |
/** Allows you to quickly add a specified number of items to the collection view's data source, and thus add the items as cells to the collection view. - parameter numberOfCells: The number of items representing UICollectionViewCells to create in your data source. - returns: The number of items created in the data source, and thus number of cells created. */ func reloadCollectionViewData(numberOfCells: Int) -> Int { if collectionViewDataSource.count == 0 { for i in 0...(numberOfCells-1) { collectionViewDataSource.append(i) } return numberOfCells; } else { return 0; } } |
Here’s what happens when I highlight the method name or parameter in Xcode and click ⌘ ⌃ ⇧ ? on the keyboard:
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:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
@interface ViewController : UIViewController /*! Given an array of NSURLs, write all of them to console and report the number of URLs written. @param listOfURLs An array containing a list of NSURLs. @returns Number of NSURLs written to console. */ - (NSUInteger)listURLs:(NSArray *)listOfURLs; @end |
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:
|
1 2 3 4 5 6 7 8 9 |
- (NSUInteger)listURLs:(NSArray *)listOfURLs { for (NSString *stringURL in listOfURLs) { NSLog(@"URL: %@", stringURL); } return [listOfURLs count]; } |
Here’s what happens when I highlight the method name or parameter in Xcode and click ⌘ ⌃ ⇧ ? on the keyboard:
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.
