Documentation Comments In Xcode
Daily Coding Tip 010
When you hold the option (⌥) key and click on any Apple system class, function, or property, you’ll get a pop-up window that tells you more about it. Another way to view this information is to use the right panel, which has a question mark tab at the top for Quick Help. You can press the combination of option (⌥), command (⌘) and 3 to bring up Quick Help in the right panel for whatever is where the typing cursor currently is.
It should be obvious that this documentation is separated into many sections. The declaration is automatically generated, and therefore it is always included. Everything else can be added to your custom functions, classes and properties. A comment block starting with /** can be added above anything, with the first line being a brief summary and a second line being a more detailed description. I’ve included everything else that Xcode will recognize and put under a heading, including the ability to explain your parameters and your return type.
| /** | |
| A summary of what the function does | |
| A longer description of what the function does | |
| - Author: | |
| Rob Sturgeon | |
| - Returns: | |
| The sum of the two numbers | |
| - Throws: | |
| If the function threw an error, it would be explained here | |
| - parameters: | |
| - number1: The first integer | |
| - number2: The second integer | |
| - Important: | |
| A reminder of something you shouldn't forget | |
| - Version: | |
| 1.0 | |
| */ | |
| func sum(number1: Int, number2: Int) -> Int { | |
| return number1 + number2 | |
| } |
You are not required to add all of these fields, but it helps to add whatever is relevant to what your code does. Someone else reading your code can access Quick Help and get more information, even if that person is you after a lot of time has passed and you’ve forgotten why you did it. This is especially useful at the point where classes are created, functions are called, or properties are assigned to.
Using Quick Help in these situations allows you to access the documentation comment, even if you’re nowhere near the file where it was written.