/ objective-c

Documenting your iOS code : in a mandatory way

When you start working on a project, what you really love, is that code is explained with comments, and you can understand in few seconds how to use a method or what is the purpose of this method… But… This, rarely happens!!!

Indeed, on some projects, the dead line is so short, that most of the time, developers write without explaining what their code will do. I mean, you can't effectively document everything since, for example, the method - (void)setView:(UIView *)view of a controller is obvious, just because of its name.

In such a case, it would be a good practice to explain what this method do in a simple way like this :

/*!
 * @brief Set the view of the controller
 * @param view The view to set to the controller
 */
- (void)setView:(UIView *)view; 

So, there is a way to make your developers comment and document their code, informing them every time they missed documenting, or when they incompletely did it, by omitting the description of what one of the parameters the method expect.

So how to do such a thing. We could use AppleDoc for that. AppleDoc is a program that crawl all your source files looking for documented code, in order to produce a documentation that looks like the real Apple documentation.

One could have used doxygen, but for iOS applications, AppleDoc integrates in a better way.

Using AppleDoc

First of all, you should find and install AppleDoc. Get it from their website or GitHub, since I think, they link to their github repository.

Then clone it to a place of your choice, and build the project. It will produce the appledoc binary that we will use later. For more explanations on how to install it, here is the link to the github repository of appledoc where you'll find information on how to do it.

Creating the documentation checking script

Once you've installed, and compiled appledoc you are going to create a directory in your project tree, so that it will make it available for everyone working on your project. They are other place you could put the script if you don't want to follow those guidelines step by step, and then it's up to you.

This script will do the following job :

  • It will search in all .h files of your source dir, it will exclude the .m files, because, documenting header is enough for me, but you could remove the --ignore "*.m" directive if you'd like the .m files to be also fully documented.
  • It will not generate documentation, but just throw every warning about undocumented source files.
#!/bin/sh

pwd
./Scripts/documentation/appledoc \
--templates ./Scripts/documentation/Templates/ \
--project-name appledoc \
--project-company "company_name" \
--company-id com.company_name \
--warn-undocumented-object \
--warn-undocumented-member \
--warn-empty-description \
--warn-unknown-directive \
--output ~/help \
--no-create-html \
--explicit-crossref \
--ignore "*.m" \
--search-undocumented-doc \
path/to/your/sources/directory

#--keep-undocumented-objects \
#--keep-undocumented-members \

We will then make a link between this script and XCode. The result we'd like to obtain is that every time you build your project, you launch that script and it will warn you about those missing documented files. We can achieve this by :

"build_phase"

  1. Going to the Build Phases of your project's target in Xcode. Select the project in your project tree and then in the editor panel, select your build target.
  2. Add a new Build phase of type run script by clicking the bottom right button Add Build Phase. It will add a run script at the end of the build phases of your project.
  3. Then enter the path of the script that checks for the documentation. In the following screenshot, the name is build_documentation.bash but you should have the path to the check_documentation.sh script file instead.

"build_doc"

Now, we're almost there. We have a script that will warn your developers that they missed some documentation in the project, but, you know what? Warnings doesn't afraid some developers.

So this is perhaps the most pedantic part of this post. What you can do know is to tell the compiler that every warning should be considered as en Error. That way, if you forget to document your code, you won't be able to compile your project until you fill it with the correct values.