Using AppleDoc to generate Xcode help (Part 2)

PLEASE NOTE: This article was written for XCode 4.6.3 and may be outdated on some parts. See the AppleDoc issue tracker on github for more info.
Welcome to part 2. In part 1 I talked about what AppleDoc is, what it does, and how to install it in your build setup. But to actually use it is a different subject. Not a lot of documentation on how to actually use appledoc is available.
The lack of documentation is partly there because new work on AppleDoc is going on behind the scenes, and the author decided to remove the little documentation to avoid mistakes and misinformation. I found out a lot of syntax stuff on my own (partly by browsing the apple doc source code). I’d like to share my findings here, and hope that someday the official documentation gets published again. I will be happy to help writing them when the time comes.
Let us skip the history lesson and rejoice that appledoc is free and open source. Then read on to find out how to document your classes, methods, categories and enums.

Adding comments

If we looks at the generated documentation from the tutorial in part 1, you will notice that all the classes and other objects are there. You can see them, but there is no text. To add text to these generated pages, you will need to add comments in the header files. Here is an example of a single line comment for a ViewController (ViewController.h):
 /** This view controller is the main controller of this application */
@interface ViewController : UIViewController

It is important that you add two asterisks (*) and not one. This is to distinguish normal comments from documentation comments. Now, when we build the documentation target, the following should be the result (build, show organizer,  open documentation tab, [your project]:

You can also use multiple lines. You do not have to start each line with a ‘*’, but when you do, you need to do them all (otherwise the parser thinks you want to do a bullet list).
  * Both these comment styles are equivalent

Both these comment styles 
are equivalent
The comments you write can contain easy layout commands using a syntax called markdown. It lets you type Strong, Italics, headers and even tables to document your code. Consider the following example:
 /** This is some sample documentation

Above was the abstract, the rest of the comment is used for the
discussion section of the documentation. Notice I did an
unintentional line wrap. Just like html, the document will
reflow to fit the width of the available page.

Let's do a simple bullet list:

* this is the first line
* this is the second line

#Section two# 
That was a H1 header we just generated.  Want a hyperlink? Just 
type and it'll  magically turn
into a link.

Finally, a small table

| header1 | header2 | header3 |
| normal  |  center |  right  |
| cell    | cell    | cell    |
@interface ViewController : UIViewController


I find that pretty awesome. If you want to know all you can do with markdown, check this markdown reference/tutorial on Appledoc will understand most of it.

Classes, properties, methods

Until now, we’ve only added basic header comments to a class header file. Let’s apply what we’ve learned to the properties and method signatures:
 /** Documenting the sample class */
@interface SampleClass : NSObject

/** Documenting a property */
@property (nonatomic, strong) NSString *name;

/** Documenting an instance method */
-(id)initializeWithName:(NSString *)name;

/** Documenting a class method */
Now, when you build the documentation, you will get a warning: we didn’t document the name argument for initializeWithName! That’ll be our next step.

To fix this error, we need to learn a new trick to tell appledoc the which argument to document.
 /** Documenting an instance method
 @param name The name of the class
 @return Returns a named instance of SampleClass 
-(id)initializeWithName:(NSString *)name;
The @param directive is followed by the name of the property to be documented. The rest that follows is the explanation. Also note the @return directive (which is optional by the way). It does the same for the return value. As you see @return does not need a name.

This are the common directives:

  • @param [param name]
  • @returns
  • @see [classname, category name, enum typedef and such]
  • @since [version number]
  • @exception [exception]
  • @warning
  • @bug
  • @deprecated

These directive should work for all top-level objects. There are some edge cases that a directive is not fully supported though, keep that in mind. Finally there are some directives that are not supported but still caught by appledoc to be compatible with headerDoc-commented sources. These include @abstract, @brief and @discussion or @details. Sections listed under these 4 directives are automatically added to the relevant parts.

I want to close with a little tip. Appledoc builds up the documentation by parsing the source files of your project. It doesn’t use reflection on the compiled binary like the .Net document generators do. So appledoc needs to parse your files. It doesn’t check your project file to check what classes to document. Appledoc just enumerates the files and directories in your project folder and scans them all for source code. Remember that when you are suddenly confronted with strange classes in your documentation that you removed from the project earlier.
This should get you going.  As always, if you have questions, comments or suggestions, comment below or use the contact page. Happy Documenting!Rob.

Using AppleDoc to generate Xcode help (Part 1)

PLEASE NOTE: This article was written for XCode 4.6.3 and may be outdated on some parts. See the AppleDoc issue tracker on github for more info.

While developing SimplyStats I had to learn a lot of new stuff, and having integrated help certainly helps in those situations. Apple’s Xcode comes with a good set of documentation for all its classes, and can be accessed right from your code. To look up a keyword, just opt-click and you’ll get all the information you need (now if somebody integrates queries in the IDE he’d be my hero).

Wouldn’t it be cool if that was possible for your own static libraries? Well you can! In these days and ages of open source and community development it’s not a strange thing that others will use your excellent coding efforts, so providing a descent help set will certainly be appreciated.The help system for Xcode is called a ‘documentation set’ (or docset for short). Constructing a docset manually is a hell of a job. Nobody wants to construct XML files and references by hand. Fortunately there are quite a few (free!) tools that can extract comments from your code and translate them into neat docsets. There’s appledoc, doxygen and headerdoc just to name a few. I decided to go for appledoc for its simplicity.In this tutorial i will explain the steps necessary to get your code documentation up and running. This is part 1 about installing appledoc and configuration a build target. In part 2 i will explain more about the options and documentation syntax.


Just over a month and i am pleased

On June 11 of 2013, my first app was released to the world. In the first week, i had an average of 10 visitors per day with about 15 screen views total. Clearly users were checking out the app but didn’t make any significant use of it.

Now were are a little over a month further, you are clearly liking SimplyStats! Check out this graph today we topped 880 screen views and 170 visits daily!

SimplyStats release 1.2

SimplyStats 1.2 screenshotSimplyStats 1.2 screenshot

Already the 3rd release! This is just a little update, with some graphical tweaks and cleanups, like icons and a more consistent look and feel. Oh, and it now comes with a daily overview so you can monitor how your day is doing.

Get your updates from the App store or check the SimplyStats page to get you directly there.

Tips, suggestions? Use the comments below or use the contact page!

Do not choose between performance and clean code

While browsing through programmers questions on stackexchange i stumbled on this question about maintenance, and if it is acceptable to allow ugly code for performance reasons. This was one of the responses:

In layman’s words:

– Making the code ugly does not make it fast.
– Making the code clean does not make it slow (or fast).
– Making the code ugly does make the maintainer’s work slower.
– Clean code usually means the code was made by someone who cares.
– One who cares to make his code clean, usually cares to make it efficient.
– Hardware becomes cheaper with time.
– Programmers don’t get cheaper over time.
– CPU time is cheaper than programmer’s time.
– Some performance problems can be solved by throwing money at them.
– Very few code maintainability problems can be solved by throwing money at them.

Ask yourself if these statements apply to you and your product, and i hope you soon realize there is little excuse for ugly solutions.

What do you think?

Drawing iOS icons just became easier

When doing retina ready apps (is there any other way?), you need crisp graphics. I tried several alternatives until i found the excellent Mopishape Draw app for Mac.

Mopishape allows you to draw perfectly grid-aligned curves and export them to several formats. And with the latest 1.30 update it even can automatically export your @2x files for you. It’s not expensive either.

It takes a little getting used to, and it doesn’t have all the features that for example Sketch has, but it suits my needs. I am not a graphics designer you know!

Mopishape screenshot

SimplyStats reached 140 downloads!

Completely against my expectations, SimplyStats was downloaded a whopping 140 times in June. I’d like to thank everybody for helping out and I hope you all enjoy SimplyStats. 
Of course SimplyStats wouldn’t be Simply Stats without some meta-statistics (yes the app is tracking itself). Here’s some exported graphs (click to enlarge). I must add that these statistics include usage data from testing the app before June 11 and the figures are biased. After I released the app, i blocked all data coming from my testing.
Yesterday i submitted SimplyStats 1.2 to the App Store for review. I suspect that it will be approved somewhere next week. I hope it’ll draw more downloads…

Thanks for downloading and using SimplyStats!!