business@innofied.com

US Toll-Free - +1 866 941 5117

Top
documentation

Function Documentation in Xcode

Introduction:

Thousands of stunning apps are uploaded to iTunes App Store every day. Some of them become extremely popular and receive high number of downloads. However, maintenance of these app projects is critical. Strict and effective coding guidelines can only ensure proper maintenance of a project because a properly documented code requires least effort for maintenance.

Proper documentation of code is a large subject. In this blog we will only concentrate on how to write Apple like function documentation in Xcode, the IDE to develop apps for iOS and Mac.

Good Code = Documented Code

Developers do write hundreds of lines of code every day. However, most of them become less responsible while documenting their code. Going through someone else’s code is a nightmare for any developer. But few steps can resolve the problem. One of them is to write down the characteristics of a function for better understanding as well as maintenance of the project.

Method Documentation – What’s That?

You might have noticed how Apple provides method documentation, developers can access the documentation by pressing and holding the ALT key with left mouse click over a specific method. Here is an example screen-shot.

Apple's Method Documentation Apple’s Method Documentation

Want the same feature for your code? You will be able to do that after reading this article.

Let’s start documenting your own function. Before that download the empty scratch project from GitHub.

Documenting a Function/Method:

Open the downloaded project with Xcode. Create a child class of UIView named MyView.

Declare the following method in the MyView.h.

-(UIButton*)createButtonAtPoisition:(CGPoint)position ofWidth:(float) width andHeight:(float)height;

To see this method’s documentation press and hold the ALT key and click on this method. You will see something like this: Screen Shot 2014-10-07 at 5.59.47 PM

41tn3sTdEkL

Can you just add the following code snippet just above the function declaration?

/**
 *  This method creates UIButton with blue background.
 *
 *  @param position Origin point of the button.
 *  @param width    Width of the button
 *  @param height   Height of the button
 *
 *  @return Custom button with specified origin and width, height.
 */

Now press and hold the ALT key and click on the method. You will see something like this:

Screen Shot 2014-11-10 at 12.43.03 PM

 

bingo-clip-art2

If you are still seeing the previous simple documentation, then clean your project by Shift+ Command + K. Hope this will work for you.

 

Having a Closer Look on Documentation:

Let’s have a closer look on the method documentation view. Try to figure out which code snippet has created which documentation part.

Screen Shot 2014-11-11 at 11.53.16 AM

                          Code                           Documentation

 

Making Documentation More Informative:

So now onwards you can create function documentation for your code. What about adding some more features in our function documentation? Let’s try.

Addition 1:

Find this in documentation code:

This method creates a UIButton with blue background.

Add the following lines of code on top:

 *  @author         Dummy Geek
 *  @version        1.0.1
 *  @since          1.0

Now the total documentation code becomes

/**
 *  @author         Dummy Geek
 *  @version        1.0.1
 *  @since          1.0
 *  This method creates UIButton with blue background.
 *
 *  @param position Origin point of the button.
 *  @param width    Width of the button
 *  @param height   Height of the button
 *
 *  @return Custom button with specified origin and width, height.
 */

Press and hold ALT key and click on the method – you will see something like this:

Screen Shot 2014-10-07 at 6.58.17 PM

Addition 2:

Add the following code at the bottom of the documentation comment:

 *  @note           Certains usages limination can be added here.
 *  @see            For more details see <a href="https://developer.apple.com/library/ios/documentation/windowsviews/conceptual/viewpg_iphoneos/windowsandviews/windowsandviews.html">View Programing Guidelines from Apple</a>

This is how the documentation looks now.

Screen Shot 2014-10-07 at 7.29.38 PM

 

Great!!! Now you can hyperlink to documentation. Isn’t it nice? What about adding a code snippet to the documentation? Let’s try.

Addition 3: Not finished yet

Replace the @note tag with the following documentation code

 *  @note           You may also try to implement the function with the following style.
 *  @code
 *  - (UIButton*) createButtonWithRect:(CGRect)rect
     {
        // Write your code here
     }
 * @endcode

And this is how the documentation looks like:

Screen Shot 2014-10-07 at 7.45.09 PM

 

Finally, the code is in the documentation. If you face any problem you can download the complete project from GitHub.

Where to go from here?

You might be happy to learn a good feature about documentation. But the coding world has gone far since you have started reading this blog. Some coders are too good to be lazy. Now a days almost every problem has a ready made solution. There are plugins to create documentation for a method. VVDocumenter is one of them. Download it from GitHub. For user’s manual follow the ReadMe file of the repository. This will automatically add common tag like Description, @param, @return, @brief but for special tags like  @note, @code, @see, @version etc are not added automatically. You need to manually insert them.

 

Sauvik Dolui

Sauvik Dolui is an iOS enthusiast and ingenious blogger who loves all things design and technology. He works closely with clients across Fortune 500 companies to develop an effective technical strategy. Besides iOS apps he also loves to develop cross-platform mobile games. The Little Indian Archer, a bow-arrow game developed by Sauvik, can be found on App Store and Play Store as well. When he is not coding, he can be found travelling around the villages or reading a book. By the way he is crazy about soccer.