When we talk about documenting a code, apparently, it doesn’t mean adding a few comments on the methods of your implementation files. It’s definitely more than that. A good application is not just about writing a clean code, its also about how well its being understood by others. No matter how well-written the code is, if there is no detailed documentation created along with it, chances of trouble arising in future is higher. The worst decision, you might make during the application creation period, would be to skip the comments, even if you are the sole developer or working in a team.
Xcode 5 and Document Support
That said, let us start with the support that Xcode provides to document your code. A small addition was mentioned during the Xcode 5 and iOS 7 announcements that most people might have missed: HeaderDoc and Doxygen. Most of you, as a developer, might have seen that the in-built framework classes and functions are described in the Quick look panels of the XCode. It is possible to have the same effect in your code, also, using the correct format for commenting.
Xcode parses HeaderDoc-style comments behind the scenes to, automatically, present your documentation in quick look panels.
The simplest commenting technique you must have used for sure is:
But documenting code is more that this simplest form. Code documentation is a structured way to write comments using the special keywords/tags so that the compiler understands it and help you and others in future implementation.
Using these, your documentation can be displayed in three different places:
1. Quick Help Inspector – In the Utilities panel.
2. Help Popup – That is displayed when you press the Option key and click on the name of method, class or property.
3. In the code-completion popup.
There are three possible ways to mark a documentation area when writing code in Objective-C.
It is interesting to note that it is incredibly simple and easy to add documentation to a property. For e.g. Add the option on a property, as below, and when option is -clicked, this popover will be shown:
In case of commenting on functions, you can use header tags which will provide more details of the methods. Let us see how that is achieved now.
There are 2 types of tags:
- Top-Level Tags: These are the tags that declare the type of item/parameter you are commenting on (Headers, classes, methods, etc).
- Second-Level Tags: These tags help to give more detail about the specific item/parameter you are commenting on.
Let us concentrate on the second level tags, first. Some of the tags are as follows:
- @code — @encode
You can find a full list of all supported tags in HeaderDoc UserGuide.
Code Documenting in Objective C
Let us learn how these can be, actually, used in the code. Documenting a method can be done as follows:
For example: Let us add a @description tag, two @param tags and a @return tag to the function as follows:
On Option + Click, you can see the following window. You can, also, check the Quick Help in the Utilities panel. You will find the same description there, too.
The code completion popup, which is displayed, when you write the function name, will now include the description of the function, along with the method quick view.
Other options, you can include in the commenting, are @codes, @warnings, etc. Please refer the below sample:
And the result is as follows:
iOS and Swift Developer, RapidValue Solutions