Documenting Objective-C Code

Hello there! 🙂

A you might be knowing as a programmer, documenting is important for any code even though it is not the most interesting part of programming.

There are a number of tutorials available for documenting your Objective-C code and generating Apple’s Cocoa like manuals.
In this post we will look at the most simple way of doing it using HeaderDoc.

If you want to dig deeper into the topics, I recommend you go through the links at the end of this post. There are links to detailed blog posts and also Apple documentation on few tools.

What you will achieve?

  1. You will be adding lovely readable comments to your code.
  2. You will get quick help on the methods. (The pop up you see when you option-click on a cocoa method which contains the method description.)
  3. A documentation file in HTML very much like Apple’s Cocoa documentation.

How do I do that?

  1. Add comments to your methods in the specific format. (You will achieve goals 1 & 2 with this.)
  2. Execute a command to generate a HTML docset.

1. Adding comments to code:

Follow the below format to add appropriate comments to your code.
/*!
* @brief This is in brief of what this method does.
* @discussion
*	This is a detailed discussion of what the method does.
* 	It can run through multiple lines.
* @param aParm This is the parameter you need to pass to this method.
* @return This is what the method returns to you.
*/

Now when you are calling this method, you can see the above details in quick completion and quick help.
* (If you do not see immediately try building the app once after you have added the comments)

Auto Complete Suggesstion
Auto Complete Suggesstion
Quick Help Popup
Quick Help Popup

2. Generating HTML document:

  1. Open Terminal (or Spotlight search “terminal”)
  2. Got to the project directory where you have the .xcodeproj file (say myProject)
  3. Run the command headerdoc2html -o ./myOutputDicrectory/ myProjectDirectory/
$ cd /myProject/ 
$ headerdoc2html -o ./documentation/ myProject/ 

This will create a documentation folder within your project folder and have multiple folders for each of your classes. You can now open the index.html file and view the documentation for any particular class. If the class is say viewController.h then the file is viewController_h/index.html

HTML Document
HTML Document

Thats it! 🙂

For detailed reads go through the below blogs/tutorials and documentations.


References:

There are multiple tools available currently few of the commonly used ones are: Doxygen, HeaderDoc (used in this tutorial) and AppleDoc.

Doxygen and HeaderDoc:

  1. Apple Developer Articles: Doxygen and HeaderDoc
  2. RayWenderlich Tutorial
  3. NSHipster Guide
  4. AppCoda Guide

Apple Doc:

  1. Creator: GentleBytes
  2. GitHub Source
  3. COCOANETICS Guide

(This is even used by apple for their new open source project: ResearchKit’s documentation.)

Swift documentation: (In the works!)

  1. NSHipster Guide

Thanks for visiting! 🙂

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s