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?
- You will be adding lovely readable comments to your code.
- 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.)
- A documentation file in HTML very much like Apple’s Cocoa documentation.
How do I do that?
- Add comments to your methods in the specific format. (You will achieve goals 1 & 2 with this.)
- 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)
2. Generating HTML document:
- Open Terminal (or Spotlight search “terminal”)
- Got to the project directory where you have the .xcodeproj file (say myProject)
- 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
Thats it! 🙂
For detailed reads go through the below blogs/tutorials and documentations.
There are multiple tools available currently few of the commonly used ones are: Doxygen, HeaderDoc (used in this tutorial) and AppleDoc.
Doxygen and HeaderDoc:
- Apple Developer Articles: Doxygen and HeaderDoc
- RayWenderlich Tutorial
- NSHipster Guide
- AppCoda Guide
Swift documentation: (In the works!)
Thanks for visiting! 🙂